|
|
Tech Note 13: Using the ScreenLib LibraryMay 01, 2008© NSB Corporation. All rights reserved. |
(Special thanks to Ron Glowka)
The ScreenLib Library adds functions to NS Basic to enhance control of the screen. It allows you to change the bit depth and color attributes. There are also drawing functions and a screen lock function. A sample program demonstrating the use of the functions called ScreenLibTest is also included.
By providing access to the WinScreenMode API function, ScreenLib provides methods for determining a device's bit depth and color capabilities and for setting the "screen mode" to take advantage of these capabilities. It eliminates the need for using third-party applications to perform these functions prior to running your NS Basic program.
A copy of the documentation for the WinScreenMode API function is provided at the end of this document. This documentation should be reviewed to gain a more full understanding of this function.
Color support in NS Basic may work differently than you are used to. Each of the UI elements on the screen has its own color setting. However, the settings apply equally to all objects on the screen.
More information on using color capabilities can be found in the "Tech Note 04: Using Color Objects and Graphics" contributed by Adrian Nicolaiev. This Tech Note can be found at:
http://nsbasic.com/symbian/info/technotes/TN04.htm
All of the "SysTraps" mentioned in Tech Note 4, plus a few others, are now supported in this library. While most of these functions can be called using the built-in SysTrapSub and SysTrapFunc statements, they have been included here to make them easier to call and are somewhat more "self documenting".
In order to use the ScreenLib Library, the library must be loaded using the NSBasic LoadLibrary statement. This statement should be located in the program's Startup code so that the functions will be available throughout the program. The LoadLibrary statement has an optional second parameter to allow you to specify an abbreviated reference name for the library's functions. The examples in this document use "SL" for this reference name. Example:
Program's Startup code: Sub main() LoadLibrary "ScreenLib", "SL" End Sub
Also, in order to use the ScreenLib Library, the ScreenLib.INF file must be present in your "nsbasic\lib" directory and the ScreenLib.prc file must be added to your project as a resource.
The functions in this library are also contained in the general purpose SystemLib library. They are presented here as well with additional documentation.
Except for the function that returns a version number, all the parameter and return data types are either "Integer"or "String". Version numbers are returned as a "Double".
Version
-------
Version = ScreenLib.Version()
Description:
Returns the version number of the ScreenLib Library.
Parameters: None
Returns: Version as Double
Example:
Dim Version as Double
Version = SL.Version()
CompileInfo
-----------
ScreenLib.CompileInfo CompileDate, CompileTime
Description:
Returns the date and time that the ScreenLib Library
was compiled.
Parameters: CompileDate as String
CompileTime as String
Returns: None
Example:
Dim CompileDate as String
Dim CompileTime as String
CompileDate = "mon dd yyyy" '11 characters
CompileTime = "hh:mm:ss" '8 characters
SL.CompileInfo CompileDate, CompileTime
Comments:
The CompileDate and CompileTime string variables must be
initialized prior to calling CompileInfo.
GetSupportedDepths
------------------
Depths = ScreenLib.GetSupportedDepths()
Description:
Returns a bitmapped integer with each bit indicating a
bitmap depth supported by the device.
Parameters: None
Returns: Depths as Integer
Example:
Dim Depths as Integer
Depths = SL.GetSupportedDepths()
Comments:
The NS Basic Library "BitsNBytes" probably provides
the best suited functions for evaluating the returned value
from this function.
DepthSupported
--------------
Boolean = ScreenLib.DepthSupported(Depth)
Description:
Returns 1 if the specified depth is supported by the
device. Otherwise, it returns 0.
Parameters: Depth as Integer
Returns: Boolean as Integer
Example:
Dim Boolean as Integer
Dim Depth as Integer
Depth = 4
Boolean = SL.DepthSupported(Depth)
ColorSupported
--------------
Boolean = ScreenLib.ColorSupported()
Description:
Returns 1 if the device has color capabilities.
Otherwise, it returns 0.
Parameters: None
Returns: Boolean as Integer
Example:
Dim Boolean as Integer
Boolean = SL.ColorSupported()
SetDepth
--------
ScreenLib.SetDepth Depth
Description:
Sets the screen mode to support the specified bitmap
bit depth.
Parameters: Depth as Integer
Returns: None
Example:
Dim Depth as Integer
Depth = 4
SL.SetDepth Depth
SetColor
--------
ScreenLib.SetColor Boolean
Description:
Sets the screen mode to support color bitmaps.
Parameters: Boolean as Integer
(1 = support color)
(0 = do not support color)
Example:
Dim Boolean as Integer
Boolean = 1
SL.SetColor Boolean
SetWidth
--------
ScreenLib.SetWidth Width
Description:
Sets the current screen width.
Parameters: Width as Integer
Returns: None
Example:
Dim Width as Integer
Width = 160
SL.SetWidth Width
Comments:
This function does not appear to work correctly with NS Basic
programs.
SetHeight
---------
ScreenLib.SetHeight Height
Description:
Sets the current screen height.
Parameters: Height as Integer
Returns: None
Example:
Dim Height as Integer
Height = 160
SL.SetHeight Height
Comments:
This function does not appear to work correctly with NS Basic
programs.
SaveScreenMode
--------------
ScreenLib.SaveScreenMode()
Description:
Saves the current screen mode parameters. These parameters
can later be restored by calling "RestoreScreenMode". It is
suggested that the current screen mode parameters be saved before
any changes are requested and that these saved parameters
are restored when the program exits.
Parameters: None
Returns: None
Example:
SL.SaveScreenMode()
RestoreScreenMode
-----------------
ScreenLib.RestoreScreenMode()
Description:
Restores saved screen mode parameters. These parameters
must have been saved by calling "SaveScreenMode". It is
suggested that the current screen mode parameters be saved before
any changes are requested and that these saved parameters
are restored when the program exits.
Parameters: None
Returns: None
Example:
SL.RestoreScreenMode()
CurrentDepth
------------
Depth = ScreenLib.CurrentDepth()
Description:
Returns the current bitmap depth.
Parameters: None
Returns: Depth as Integer
Example:
Dim Depth as Integer
Depth = SL.CurrentDepth()
CurrentColor
------------
Boolean = ScreenLib.CurrentColor()
Description:
Returns 1 if the device's screen mode is currently
set to support color. Otherwise, it returns 0.
Parameters: None
Returns: Boolean as Integer
Example:
Dim Boolean as Integer
Boolean = SL.CurrentColor()
CurrentWidth
------------
Width = ScreenLib.CurrentWidth()
Description:
Returns the current screen width.
Parameters: None
Returns: Width as Integer
Example:
Dim Width as Integer
Width = SL.CurrentWidth()
CurrentHeight
-------------
Height = ScreenLib.CurrentHeight()
Description:
Returns the current screen height.
Parameters: None
Returns: Height as Integer
Example:
Dim Height as Integer
Height = SL.CurrentHeight()
SetToDefaults
-------------
ScreenLib.SetToDefaults()
Description:
Sets all screen mode parameters to their default values.
Parameters: None
Returns: None
Example:
SL.SetToDefaults()
DefaultDepth
------------
Depth = ScreenLib.DefaultDepth()
Description:
Returns the default bitmap depth.
Parameters: None
Returns: Depth as Integer
Example:
Dim Depth as Integer
Depth = SL.DefaultDepth()
DefaultColor
------------
Boolean = ScreenLib.DefaultColor()
Description:
Returns 1 if the device's screen mode default is
set to support color. Otherwise, it returns 0.
Parameters: None
Returns: Boolean as Integer
Example:
Dim Boolean as Integer
Boolean = SL.DefaultColor()
DefaultWidth
------------
Width = ScreenLib.DefaultWidth()
Description:
Returns the default screen width.
Parameters: None
Returns: Width as Integer
Example:
Dim Width as Integer
Width = SL.DefaultWidth()
DefaultHeight
-------------
Height = ScreenLib.DefaultHeight()
Description:
Returns the default screen height.
Parameters: None
Returns: Height as Integer
Example:
Dim Height as Integer
Height = SL.DefaultHeight()
GetTableEntryIndex
------------------
Index = ScreenLib.GetTableEntryIndex(Which)
Description:
This function calls the UIColorGetTableEntryIndex API
function. It returns the index value for a UI color for the
current system palette.
Parameters: Which as Integer
UIObjectFrame = 0,
UIObjectFill = 1
UIObjectForeground = 2
UIObjectSelectedFill = 3
UIObjectSelectedForeground = 4
UIMenuFrame = 5
UIMenuFill = 6
UIMenuForeground = 7
UIMenuSelectedFill = 8
UIMenuSelectedForeground = 9
UIFieldBackground = 10
UIFieldText = 11
UIFieldTextLines = 12
UIFieldCaret = 13
UIFieldTextHighlightBackground = 14
UIFieldTextHighlightForeground = 15
UIFieldFepRawText = 16
UIFieldFepRawBackground = 17
UIFieldFepConvertedText = 18
UIFieldFepConvertedBackground = 19
UIFieldFepUnderline = 20
UIFormFrame = 21
UIFormFill = 22
UIDialogFrame = 23
UIDialogFill = 24
UIAlertFrame = 25
UIAlertFill = 26
UIOK = 27
UICaution = 28
UIWarning = 29
Returns: Index as Integer
Example:
Dim Which as Integer
Dim Index as Integer
Which = 11 'UIFieldText
Index = SL.GetTableEntryIndex(Which)
GetTableEntryRGB
----------------
Index = ScreenLib.GetTableEntryRGB(Which)
Description:
This function calls the UIColorGetTableEntryRGB API function.
It retrieves the RGB values for the UI Color. RGB Values are
returned in a structure called "RGBColorType". It contains the
following fields:
index, red, green, blue.
This function retrieves all these values, but only returns
the index. To get the red, green, and blue values, call this
function first and then call GetRGBRed, GetRGBGreen, and
GetRGBBlue. See the example for more information.
Parameters: Which as Integer
(see the GetTableEntryIndex function for
a list of valid "Which" values")
Returns: Index as Integer
Example:
Dim Which as Integer
Dim Index as Integer
Dim Red as Integer
Dim Green as Integer
Dim Blue as Integer
Which = 11 'UIFieldText
Index = SL.GetTableEntryRGB(Which)
Red = SL.GetRGBRed()
Green = SL.GetRGBGreen()
Blue = SL.GetRGBBlue()
GetRGBIndex
-----------
Index = ScreenLib.GetRGBIndex()
Description:
RGB Values are returned in a structure called "RGBColorType".
It contains the following fields:
index, red, green, blue.
This function returns the index value that was previously
retrieved by either the GetTableEntryRGB or IndexToRGB functions.
Parameters: None
Returns: Index as Integer
Example:
Dim Index as Integer
Index = SL.GetRGBIndex()
GetRGBRed
---------
Red = ScreenLib.GetRGBRed()
Description:
RGB Values are returned in a structure called "RGBColorType".
It contains the following fields:
index, red, green, blue.
This function returns the red value that was previously
retrieved by either the GetTableEntryRGB or IndexToRGB functions.
Parameters: None
Returns: Red as Integer
Example:
See the example provided with either the GetTableEntryRGB or
IndexToRGB functions.
GetRGBGreen
-----------
Green = ScreenLib.GetRGBGreen()
Description:
RGB Values are returned in a structure called "RGBColorType".
It contains the following fields:
index, red, green, blue.
This function returns the green value that was previously
retrieved by either the GetTableEntryRGB or IndexToRGB functions.
Parameters: None
Returns: Green as Integer
Example:
See the example provided with either the GetTableEntryRGB or
IndexToRGB functions.
GetRGBBlue
----------
Blue = ScreenLib.GetRGBBlue()
Description:
RGB Values are returned in a structure called "RGBColorType".
It contains the following fields:
index, red, green, blue.
This function returns the blue value that was previously
retrieved by either the GetTableEntryRGB or IndexToRGB functions.
Parameters: None
Returns: Blue as Integer
Example:
See the example provided with either the GetTableEntryRGB or
IndexToRGB functions.
SetTableEntryIndex
------------------
ScreenLib.SetTableEntryIndex Which, Index
Description:
This subroutine calls the IndexToRGB API function and then
it calls UIColorSetTableEntry. It changes a value in the UI
Color list.
Parameters: Which as Integer
(see the GetTableEntryIndex function for
a list of valid "Which" values")
Index as Integer (valid values: 0 to 255)
Returns: None
Example:
Dim Which as Integer
Dim Index as Integer
Which = 11 'UIFieldText
Index = 42
SL.SetTableEntryIndex Which, Index
Note:
Some changes aren't reflected until the object or form is
redrawn with the "Redraw" statement. Even then, some changes
like the form background (UIFormFill - 22) aren't reflected
until until you change forms with a "NextScreen" statement.
You might want to set some table entries in either the
programs "Startup" code or just before you use the "NextScreen"
statement.
SetTableEntryRGB
----------------
ScreenLib.SetTableEntryRGB Which, Red, Green, Blue
Description:
This subroutine calls the UIColorSetTableEntry API function.
It changes a value in the UI Color list.
Parameters: Which as Integer
(see the GetTableEntryIndex function for
a list of valid "Which" values")
Red as Integer (valid values: 0 to 255)
Green as Integer (valid values: 0 to 255)
Blue as Integer (valid values: 0 to 255)
Returns: None
Example:
Dim Which as Integer
Dim Red as Integer
Dim Green as Integer
Dim Blue as Integer
Which = 11 'UIFieldText
Red = 255
Green = 0
Blue = 0
SL.SetTableEntryRGB Which, Red, Green, Blue
Note:
Some changes aren't reflected until the object or form is
redrawn with the "Redraw" statement. Even then, some changes
like the form background (UIFormFill - 22) aren't reflected
until until you change forms with a "NextScreen" statement.
You might want to set some table entries in either the
programs "Startup" code or just before you use the "NextScreen"
statement.
BrightnessAdjust
----------------
ScreenLib.BrightnessAdjust()
Description:
This subroutine calls the UIBrightnessAdjust API function.
It displays the "Brightness Adjust" dialog.
Parameters: None
Returns: None
Example:
SL.BrightnessAdjust()
ContrastAdjust
--------------
ScreenLib.ContrastAdjust()
Description:
This subroutine calls the UIContrastAdjust API function.
It displays the "Contrast Adjust" dialog.
Parameters: None
Returns: None
Example:
SL.ContrastAdjust()
Note:
This function may not work on all devices.
PickColorIndex
--------------
Changed = ScreenLib.PickColorIndex(Index, Title)
Description:
This function calls the UIPickColor API function. It
displays a Palette dialog to allow a user to select a
color. The selected index and RGB values can be retrieved
by calling the GetRGBIndex, GetRGBRed, GetRGBGreen and
GetRGBBlue functions.
Parameters: Index as Integer - suggested Index
Title as String - Dialog title to display
Returns: Changed as Integer
(0 = User cancelled or chose suggested index)
(1 = User chose a new index)
Example:
Dim Index as Integer
Dim Red as Integer
Dim Green as Integer
Dim Blue as Integer
Dim Changed as Integer
Dim Title as String
Index = 42
Title = "Pick a Color"
Changed = SL.PickColorIndex(Index, Title)
If Changed = 1 Then
Index = SL.GetRGBIndex()
Red = SL.GetRGBRed()
Green = SL.GetRGBGreen()
Blue = SL.GetRGBBlue()
End If
PickColorRGB
--------------
Changed = ScreenLib.PickColorRGB(Red, Green, Blue, Title)
Description:
This function calls the UIPickColor API function. It
displays an RGB dialog to allow a user to select a
color. The selected index and RGB values can be retrieved
by calling the GetRGBIndex, GetRGBRed, GetRGBGreen and
GetRGBBlue functions.
Parameters: Red as Integer - suggested red value - 0 to 255)
Green as Integer - suggested green value - 0 to 255)
Blue as Integer - suggested blue value - 0 to 255)
Title as String - Dialog title to display
Returns: Changed as Integer
(0 = User cancelled or chose suggested RGB values)
(1 = User chose new RGB values)
Example:
Dim Index as Integer
Dim Red as Integer
Dim Green as Integer
Dim Blue as Integer
Dim Changed as Integer
Dim Title as String
Red = 255
Green = 0
Blue = 0
Title = "Pick a Color"
Changed = SL.PickColorRGB(Red, Green, Blue, Title)
If Changed = 1 Then
Index = SL.GetRGBIndex()
Red = SL.GetRGBRed()
Green = SL.GetRGBGreen()
Blue = SL.GetRGBBlue()
End If
IndexToRGB
----------
ScreenLib.IndexToRGB Index
Description:
This subroutine calls the WinIndexToRGB API function. It
converts an index in the currently active color table to an
RGB value. RGB Values are returned in a structure called
"RGBColorType". It contains the following fields:
index, red, green, blue.
To get the actual index, red, green, and blue values, call this
function first and then call GetRGBIndex, GetRGBRed, GetRGBGreen,
and GetRGBBlue. See the example for more information.
Parameters: Index as Integer
Returns: None
Example:
Dim Index as Integer
Dim Red as Integer
Dim Green as Integer
Dim Blue as Integer
Index = 134
SL.IndexToRGB Index
Index = SL.GetRGBIndex()
Red = SL.GetRGBRed()
Green = SL.GetRGBGreen()
Blue = SL.GetRGBBlue()
RGBToIndex
----------
Index = ScreenLib.RGBToIndex(Red, Green, Blue)
Description:
This function calls the WinRGBToIndex API function. It
converts RGB values to the index of the closest color in the
currently active color lookup table (CLUT).
Parameters: Red as Integer (valid values: 0 to 255)
Green as Integer (valid values: 0 to 255)
Blue as Integer (valid values: 0 to 255)
Returns: Index as Integer
Example:
Dim Index as Integer
Dim Red as Integer
Dim Green as Integer
Dim Blue as Integer
Red = 255
Green = 0
Blue = 0
Index = SL.RGBToIndex(Red, Green, Blue)
SetForeColor
------------
OldIndex = ScreenLib.SetForeColor(NewIndex)
Description:
This function calls the WinSetForeColor API function. It
sets the foreground color to use in subsequent draw operations.
Parameter: NewIndex as Integer
Returns: OldIndex as Integer - previous foreground index
Example:
Dim OldIndex as Integer
Dim NewIndex as Integer
NewIndex = 134
OldIndex = SL.SetForeColor(NewIndex)
Note:
Colors set with this function appear to be reset to default
values when switching between forms or when a form is redrawn.
It is probably best to call this function in the form's
"After" code section.
SetBackColor
------------
OldIndex = ScreenLib.SetBackColor(NewIndex)
Description:
This function calls the WinSetBackColor API function. It
sets the background color to use in subsequent draw operations.
Parameter: NewIndex as Integer
Returns: OldIndex as Integer - previous background index
Example:
Dim OldIndex as Integer
Dim NewIndex as Integer
NewIndex = 134
OldIndex = SL.SetBackColor(NewIndex)
Note:
Colors set with this function appear to be reset to default
values when switching between forms or when a form is redrawn.
It is probably best to call this function in the form's
"After" code section.
SetTextColor
------------
OldIndex = ScreenLib.SetTextColor(NewIndex)
Description:
This function calls the WinSetTextColor API function. It
sets the color to use for drawing characters in subsequent draw
operations.
Parameter: NewIndex as Integer
Returns: OldIndex as Integer - previous text index
Example:
Dim OldIndex as Integer
Dim NewIndex as Integer
NewIndex = 134
OldIndex = SL.SetTextColor(NewIndex)
Note:
Colors set with this function appear to be reset to default
values when switching between forms or when a form is redrawn.
It is probably best to call this function in the form's
"After" code section.
DrawLine
--------
ScreenLib.DrawLine X1, Y1, X2, Y2
Description:
This soubroutine calls the WinDrawLine API function. It
draws a line in the draw window using the current foreground
color.
Note: This function was provided for completeness only. The
built-in DrawLine NSBasic statement produces the same result.
Parameters: X1 as Integer
Y1 as Integer
X2 as Integer
Y2 as Integer
Returns: None
Example:
Dim X1 as Integer
Dim Y1 as Integer
Dim X2 as Integer
Dim Y2 as Integer
X1 = 10
Y1 = 20
X2 = 120
Y2 = 20
SL.DrawLine X1, Y1, X2, Y2
DrawGrayLine
------------
ScreenLib.DrawGrayLine X1, Y1, X2, Y2
Description:
This subroutine calls the WinDrawGrayLine API function. It
does not draw in a gray color, but rather draws with
alternating foreground and background colors.
Parameters: X1 as Integer
Y1 as Integer
X2 as Integer
Y2 as Integer
Returns: None
Example:
Dim X1 as Integer
Dim Y1 as Integer
Dim X2 as Integer
Dim Y2 as Integer
X1 = 10
Y1 = 20
X2 = 120
Y2 = 20
SL.DrawGrayLine X1, Y1, X2, Y2
EraseLine
---------
ScreenLib.EraseLine X1, Y1, X2, Y2
Description:
This subroutine calls the WinEraseLine API function. It
draws a line in the draw window using the current background
color.
Parameters: X1 as Integer
Y1 as Integer
X2 as Integer
Y2 as Integer
Returns: None
Example:
Dim X1 as Integer
Dim Y1 as Integer
Dim X2 as Integer
Dim Y2 as Integer
X1 = 10
Y1 = 20
X2 = 120
Y2 = 20
SL.EraseLine X1, Y1, X2, Y2
InvertLine
----------
ScreenLib.InvertLine X1, Y1, X2, Y2
Description:
This subroutine calls the WinInvertLine API function. It
draws an inverted line in the draw window.
Parameters: X1 as Integer
Y1 as Integer
X2 as Integer
Y2 as Integer
Returns: None
Example:
Dim X1 as Integer
Dim Y1 as Integer
Dim X2 as Integer
Dim Y2 as Integer
X1 = 10
Y1 = 20
X2 = 120
Y2 = 20
SL.InvertLine X1, Y1, X2, Y2
DrawPixel
---------
ScreenLib.DrawPixel X, Y
Description:
This subroutine calls the WinDrawPixel API function. It
draws a pixel in the draw window using the current foreground
color.
Parameters: X as Integer
Y as Integer
Returns: None
Example:
Dim X as Integer
Dim Y as Integer
X = 10
Y = 20
SL.DrawPixel X, Y
ErasePixel
----------
ScreenLib.ErasePixel X, Y
Description:
This subroutine calls the WinErasePixel API function. It
draws a pixel in the draw window using the current background
color.
Parameters: X as Integer
Y as Integer
Returns: None
Example:
Dim X as Integer
Dim Y as Integer
X = 10
Y = 20
SL.ErasePixel X, Y
InvertPixel
-----------
ScreenLib.InvertPixel X, Y
Description:
This subroutine calls the WinInvertPixel API function. It
draws an inverted pixel in the draw window.
Parameters: X as Integer
Y as Integer
Returns: None
Example:
Dim X as Integer
Dim Y as Integer
X = 10
Y = 20
SL.InvertPixel X, Y
GetPixel
--------
Index = ScreenLib.GetPixel(X, Y)
Description:
This function calls the WinGetPixel API function. It
returns the color of the specified a pixel in the draw window.
Parameters: X as Integer
Y as Integer
Returns: Index as Integer
Example:
Dim Index as Integer
Dim X as Integer
Dim Y as Integer
X = 10
Y = 20
Index = SL.GetPixel(X, Y)
ScreenLock
----------
Success = ScreenLib.ScreenLock(Mode)
Description:
This function calls the WinScreenLock API function. It
"locks" the current screen by switching the UI concept of the
screen base address to an area that is not reflected on the
display. This routine can be used to "freeze" the display
while doing lengthy drawing operations to avoid a flickering
effect. Call ScreenUnlock to unlock the display and cause
it to be updated with any changes. The screen must be unlocked
as many times as it is locked to actually update the display.
Parameters: Mode as Integer
(winLockCopy = 0 - copy old screen to new)
(winLockErase = 1 - erase new screen to white)
(winLockDontCare = 2 - don't do anything)
Returns: Success as Integer
(1 = Success)
(0 = Failure)
Example:
Dim Success as Integer
Dim Mode as Integer
Mode = 0 'winLockCopy
Success = SL.ScreenLock(Mode)
ScreenUnlock
------------
ScreenLib.ScreenUnlock()
Description:
This subroutine calls the WinScreenUnlock API function. Call
ScreenUnlock to unlock the display and cause it to be updated
with any changes. The screen, which was locked by calling
ScreenLock, must be unlocked as many times as it is locked to
actually update the display.
Parameters: None
Returns: None
Example:
SL.ScreenUnlock()
Purpose:
Sets or returns display parameters, including display geometry,
bit depth, and color support.
Prototype:
Err WinScreenMode (WinScreenModeOperation operation,
UInt32 *widthP, UInt32 *heightP,
UInt32 *depthP, Boolean *enableColorP)
Parameters:
The widthP, heightP, depthP, and enableColorP parameters are used in
different ways for different operations. See Comments at the end of
this description for details.
-> operation
The work this function is to perform, as specified by
one of the following selectors:
winScreenModeGet
Return the current settings for the display.
winScreenModeGetDefaults
Return the default settings for the display.
winScreenModeGetSupportedDepths
Return in depthP a hexadecimal value indicating
the supported screen depths. The binary
representation of this value defines a bitfield
in which the value 1 indicates support for a
particular display depth. The position
representing a particular bit depth corresponds
to the value 2(bitDepth-1). See the Example at
the end of this function description for more
information.
winScreenModeGetSupportsColor
Return true as the value of the enableColorP
parameter when color mode can be enabled.
winScreenModeSet
Change display settings to the values specified
by the other arguments to the WinScreenMode
function.
winScreenModeSetToDefaults
Change display settings to default values.
<-> widthP
Pointer to new/old screen width.
<-> heightP
Pointer to new/old screen height.
<-> depthP
Pointer to new/old/available screen depth.
<-> enableColorP
Pass true to enable color drawing mode.
Result:
If no error, returns values as specified by the operation
argument. Various invalid arguments may cause this function
to return a sysErrParamErr result code. In rare cases, a failed
allocation can cause this function to return a
memErrNotEnoughSpace error.
Comments:
The widthP, heightP, depthP, and enableColorP parameters are used in
different ways for different operations. All "get" operations overwrite
these values with a result when the function returns. The
winScreenModeSet operation changes current display parameters when
passed valid argument values that are not NULL pointers. The
winScreenModeSetToDefaults operation ignores values passed for all of
these parameters.
Table 48.1 summarizes parameter usage for each operation this function
performs.
Table 48.1 Use of parameters to WinScreenMode function
Operation winScreenMode... widthP heightP depthP enableColorP
...Get returned returned returned returned
...GetDefaults returned returned returned returned
...GetSupportedDepths pass in pass in returned pass in
...GetSupportsColor pass in pass in pass in returned
...Set pass in pass in pass in pass in
...SetToDefaults ignored ignored ignored ignored
This function ignores NULL pointer arguments to the widthP, heightP,
depthP, and enableColorP parameters; thus, you can pass a NULL pointer
for any of these values to leave the current value unchanged. Similarly,
when getting values, this function does not return a value for any NULL
pointer argument.
If you change the display depth, it is recommended that you restore it
to its previous state when your application closes, even though the
system sets display parameters back to their default values when
launching an application.
Note that none of the other operations interprets the depth parameter
the same way that winScreenModeGetSupportedDepths does. For example, to
set the display depth to 8-bit mode, you use 8 (decimal) for the display
depth, not 0x08 (128 decimal).
Compatibility:
Implemented only if 3.5 New Feature Set is present. In OS versions prior
to 3.5, this function is called ScrDisplayMode. The prototype for
ScrDisplayMode is similar to WinScreenMode:
Err ScrDisplayMode ( ScrDisplayModeOperation operation,
DWordPtr widthP, DWordPtr heightP,
DWordPtr depthP, BooleanPtr enableColorP)
The only other difference between ScrDisplayMode and WinScreenMode is
that the ScrDisplayModeOperation constants begin with the prefix
scrDisplayMode rather than winScreenMode.
Example:
Here are some additional examples of return values provided by the
winScreenModeGetSupportedDepths mode of the WinScreenMode function.
This function indicates support for 4-bit drawing by returning a value
of 0x08, or 23, which corresponds to a binary value of 1000. Support for
bit depths of 2 and 1 is indicated by a return value of 0x03. Support for
bit depths of 4, 2, and 1 is indicated by 0x0B, which is a binary value
of 1011. Support for bit depths of 24, 8, 4 and 2 is indicated by
0x80008A. The figure immediately following depicts this final example
graphically.
24-bit drawing
| 8-bit drawing
| | 4-bit drawing
| | | 2-bit drawing
| | | |
1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 0 0 0 1 0 1 0
| | | |
2^23 2^7 2^3 2^1
Bit depth support indicated by interpreting 0x80008A as
binary value.