|
|
6.The Control Library 6.1
6.2
6.3
6.3.1
6.3.2
6.3.3
6.3.4
6.3.5
6.3.6
6.3.7
6.3.8
6.4
6.4.1
6.4.2
6.4.3
6.5
6.5.1
6.5.2
6.6
6.6.1
6.6.2
6.6.3
6.6.4
6.6.5
6.6.6
6.6.7
6.6.8
6.7
6.8General Info
Defining Controls
Individual Controls
Button Controls
Text Controls
Pop-up Menus
Scroll Bars and Sliders
Progress Indicators
Icons and Pictures
Time and Date
Miscellaneous Controls
Control Groups
Radio Groups and General Control Groups
Placard Areas and Window Headers
Tab Controls
Querying and Setting Control Parameters
Querying Basic Parameters
Setting Basic Parameters
Procedures and Functions for Special Controls
Bevel Buttons
Text Controls
Progress Bars
Scroll Bars and Sliders
Time and Date Displays
Menus
Icons and Pictures
Bevel Button, Image Well, and Tab Group Contents
Control Display
Other Control FunctionsReference List Control Library
Controls are graphical objects displayed in dialog boxes or windows,
which are utilized by the user to easily control the operation of a program in an
intuitive manner. You are already familiar with some of the controls, even though
you might not have been aware that they were controls. For example, buttons, radio
buttons, checkboxes, and pop-up menus - familiar to you from the Dialog Library -
are all controls. Framed boxes used to enter short texts also count as controls.
You are familiar with windows with scroll bars from the Window Library. These scroll
bars are also individual controls, which are automatically created and managed by
EasyGem. All of the controls known to you up to now are automatically (scroll bars in windows) or semiautomatically (buttons and text edit fields in dialog boxes) managed by EasyGem. This saves you a lot of programming work but also offers few options to influence the program. The Control Library now makes it possible for you to manage and position individual controls in windows and dialog boxes accurately down to the last pixel. Almost all new controls introduced by Mac OS 8.0 were implemented into the Control Library. |
6.1 General Info Controls are defined with procedures. A set of parameters is passed to these defining procedures. A number is returned to you after the procedure is called. This number is used to identify the object at any time. The principle behind this is therefore the same as for menus, dialog boxes, and windows. |
The following parameters are available: | |
Con | Control identification number. This variable returns a number used
later to address the control. Warning: Most of the controls are not available until System 8.0. If Con=0 is returned, the control does not exist on this system. |
X | X-position of the upper left corner of the control. |
Y | Y-position of the upper left corner of the control. |
W | Width of the control. |
H | Height of the control. |
T$ | Most of the controls also contain a text, which can be specified with this parameter. |
F | The individual bits have a specific meaning with this value. If bit 0 is set, the object is visible. The utilization of the remaining bits depends on the object type. |
V | This can be used to assign a specific value to some of the controls (e.g., scroll bar). This parameter, however, has a completely different meaning for certain other controls. |
Mi | Minimum value that can be accepted by the control. This parameter, however, has a completely different meaning for certain other controls. |
Ma | Maximum value that can be accepted by the control. This parameter, however, has a completely different meaning for certain other controls. |
T | Some controls have different variation types. Use this parameter to select the desired type. This parameter, however, has a completely different meaning for certain other controls. |
Act | This parameter especially offers a great many possibilities of utilizing
your controls individually. Use Act to pass a pointer to an action function, which is called whenever a user
clicks on the control. Pass Act=0 if you do not wish to define an action function. |
Note: Only a portion
of the parameters listed here are required for most of the controls, because, e.g.,
a checkbox can accept only the values 0 (not checked ) or 1 (checked) and it is thus
not necessary to indicate extra values for Mi or Ma. A variety of simplified procedures also exist for many controls. In this case, for example, EasyGem calculates the width or height of a control from other values (e.g., the control text). |
6.2 Defining Controls Controls always belong with a window or a dialog box. That means a dialog box or window has to be created before it is possible to define a control. The actual control definition is than initiated with Def_Controls and finished with End_Controls. |
Def_Controls Win |
Starts control definition in window Win. |
End_Controls |
Ends control definition. |
This results in the following line of procedure: |
Def_Controls Win:'Create controls in window or dialog
box 'with the number Win. 'This is where the individual control definitions will be listed. End_Controls |
Note: If you define the controls for a dialog box between Def_Dialog and End_Dialog, then you do not need to call Def_Controls and End_Controls anymore, because this has already been done by Def_Dialog and End_Dialog. However, for a dialog box you can also define additional controls subsequently. These then have to be enclosed with Def_Controls and End_Controls. |
Before we can start programming our first example, we have to introduce some concrete controls first. We will start with the button-shaped controls, because you are already familiar with many of them from the Dialog Library. |
6.3 Individual Controls |
6.3.1 Button Controls Button controls always have a field to click on with the mouse, which then changes the status of the button. The Control Library offers the following button types: |
Con_Button R Con,X,Y[,W,H],T$,F,Act |
Normal push button. |
Con_Iconbutton R Con,X,Y[,W,H],T$,F,Ma,T,Act |
Push button with icon. |
Con_Bevelbutton R Con,X,Y[,W,H],T$,F,T,Act Con_Bevelbutton R Con,X,Y,W,H,T$,F,Mi,Ma,T,Act |
Angular button with a great many variation options. |
Con_Checkbox R Con,X,Y,T$,V Con_Checkbox R Con,X,Y[,W,H],T$,F,V,Act |
Checkbox as known from the Dialog Library. |
Con_Radiobutton R Con,X,Y,T$ Con_Radiobutton R Con,X,Y[,W,H],T$,F,V,Act |
Radio button as known from the Dialog Library. |
Use Con_Button to generate a normal button as you already are familiar with from the Dialog
Library. Position and size can now be determined accurately and down to the last
pixel using X,Y,W,H.
All of the information is interpreted as local coordinates of the window or dialog
box for which the button is being defined. If W and H are
being omitted, EasyGem calculates the button size from the text length passed in
T$. The individual bits in F have the following meaning: Bit 0: The button is visible. Bit 1: Defines a default button. A default button is easily recognized by its wide border. The default button can also be triggered by pressing the [Return] key. Bit 2: The button is an exit button. Clicking on an exit button automatically closes a modal dialog box opened with Easy_Dialog. Bit 3: The button behaves just like a checkbox. This means that after the button has been clicked, it does not return to its original state but rather remains selected and has to be clicked again to return it to normal. In Act you can pass the address of an action function. The function is called as soon as the button has been selected, meaning as soon as the mouse was released over the button. Two parameters are passed to your action function, with the first containing the control identification number and the second a so-called part code. This is important if the control consists of several parts but has not significance for simple buttons. DEF FN My_Action(Con,Part) If you do not require an action function just set Act=0. |
Con_Iconbutton functions
the same way as Con_Button. The two additional parameters have the following meaning: In Ma, you can pass the resource ID of an icon of the type 'cicn'. You need a resource editor to generate such an icon. The Apple program "ResEdit" can be downloaded from the Apple Internet site and is sufficient for simple purposes. All resources to be used with a program should always be created in the source code file. The Omikron Basic Compiler then automatically transfers the resources to the compiled program. Use T to specify whether the icon is to be displayed to the left (T=0) or the right side (T=1) of the button text. Con_Iconbutton is available with System 8.0. |
The bevel buttons - named according to their appearance - are available
in a wide variety. They can behave like push buttons, checkboxes, or radio buttons,
you can assign icons or pictures to them, position the button text in different ways,
and all variations have bevels in different widths (3D effect). Confirmed Mac users will find their angular appearance a bit unusual but these are original objects from the Macintosh Toolbox. Bits 4 and 10 in F also have a meaning for the bevel buttons. Bit 4: After the button has been clicked, it remains selected and cannot be returned to normal by clicking again. To set the button back to normal you need the command Con_Setvalue discussed further below. This behavior is required when several bevel buttons are to be combined in one group with radio button behavior (Con_Def_Radiogroup), e.g., for tool palettes. Bit 10: The content of the button (text and/or icon) reacts with an offset (when clicked, the content moves one (1) pixel to the right and to the bottom). This creates the optical illusion of having pushed down on a button. |
A bevel button can contain other content in addition to text (an icon
or a picture). This additional content has to be available as a resource. Since several
resources are suitable for this purpose you can use Mi to pass specific values, which then determine the resource type for which
to search. Mi = 0 : Only text specified with T$. Mi = 1 : Icon suite resource (e.g., 'ICN#', 'ic14', 'ic18'). Mi = 2 : Individual icon resource type 'cicn'. Mi = 3 : Picture resource type 'PICT'. In contrast to the icon variation, this type has the advantage of not limiting pictures to any specific size. Just as for Con_Iconbutton, you pass the resource ID of the desired object (icon suite, individual icon or picture) in Ma. Use T to select from three different types of bevels (3D effect) for the buttons. T = 0 : Small bevel T = 1 : Normal bevel T = 2 : Large bevel Con_Bevelbutton is available with System 8.0. |
You already know checkboxes and radio buttons from the Dialog Library,
which is why we do not have to discuss them in detail here. However, the Control
Library offers a much more flexible way of handling these objects. The parameter V for these types determines if the object is to be selected right from the start (V=1) or not (V=0). We will discuss how to group radio buttons further down. |
After that much theory it is time for a practical, hands-on example.
Buttons with icons or pictures are not considered for the example, because these
objects cannot be defined with program texts. The sample programs in the folder DEMO
are very helpful for these cases. The following program displays a simple modal dialog box with different buttons: |
COMPILER "MIN_SIZE 1000000" COMPILER "BAS_MEM 1000000" COMPILER "Warnings off" Easy_Init Act=&FN My_Action(,) Def_Dialog Dialog1,"Bevel Buttons",1 Con_Bevelbutton Bevel1,20,20,"Push Button",%1,0,Act Con_Bevelbutton Bevel2,20,50,"Toggle Button",%1001,1,Act Con_Bevelbutton Bevel3,20,80,"Sticky Button",%10001,1,Act Con_Bevelbutton Bevel4,20,110,"Offset Button",$401,2,Act Con_Button Exit_Button,80,160,"Quit",%111,Act End_Dialog Twin_Open Win1,20,41,-640,-400,80,24,"Protocol","",G_All:'Open Text Window. Easy_Dialog Dialog1 Easy_Exit END DEF FN My_Action(Con,Part) SELECT Con CASE Bevel1 Twin_Print Win1,"Button with slight bevel and push behavior." CASE Bevel2 Twin_Print Win1,"Button with normal bevel and toggle behavior." CASE Bevel3 Twin_Print Win1,"Button with normal bevel and sticky behavior." CASE Bevel4 Twin_Print Win1,"Button with severe bevel and offset behavior." CASE Exit_Button Twin_Print Win1,"Exit Button." END_SELECT END_FN |
A modal dialog box with four different bevel buttons and one default
exit push button is generated. The simplified procedures were utilized. This provides
individual buttons in differing widths, something that does not look all that nice.
Try to change the program yourself so that all buttons are equal in width by applying
the extended procedures for the button definition. We used the same action function for all buttons, because the parameter Con in My_Action can be used to determine which button has been clicked. Of course, you can also define a separate action function for each button or pass 0 if you do not require an action function, because, for example, you do not want to determine the status of the individual objects until after the dialog box has been exited. Instructions on how to do that can be found further down. |
6.3.2 Text Controls Short texts have to be output frequently when programming user interfaces or small, framed fields to be utilized as input fields by the user are required. The following procedures are available in the Control Library for this purpose: |
Con_Static R Con,X,Y,T$ Con_Static R Con,X,Y,W,H,T$[,F] |
Static text (not editable by the user). |
Con_Edit R Con,X,Y,W,H,T$[,F] |
Editable text (changeable by the user). |
Con_Editpassword R Con,X,Y,W,H[,F] |
Editable text where the entered letters are represented by nothing more than dots. This command is especially useful for creating password queries. |
Use Con_Static to generate a static text, which is a text that cannot be changed by the
user. You are already familiar with such texts from the Dialog Library (D_Text, D_Output). Static texts are used
to explain something or point something out to the user. If you do not specify a height or width, then EasyGem calculates these values so that the text will fit into one line. But you can also spread the text over several lines by making the appropriate choice for W and H. Con_Edit provides a bordered field into which the text passed in T$ is entered. The user is then also able to change this text. T$ can be empty, of course. If the text does not fit into one line, it will distributed over several lines. If the user enters more text than fits into the field, automatic scrolling takes place. A focus ring is drawn around the currently active field if System 8.0 or later has been installed. The active field can also be identified by the blinking cursor. Con_Editpassword functions exactly the same as Con_Edit; however, text cannot be passed. The entered letters are not displayed either but are represented by thick dots. This procedure - as the name implies - is used to define fields for the password query. Con_Editpassword is available with System 8.0. |
Example: |
COMPILER "MIN_SIZE 1000000" COMPILER "BAS_MEM 1000000" COMPILER "Warnings off" Easy_Init Def_Dialog Dialog1,"Text Controls",1 Con_Static Static1,20,20,"This is a static text without wrapping." Con_Static Static2,20,40,100,60,"This is a static text with wrapping." Con_Edit Edit1,20,120,200,60,"This text can be edited." Con_Static Static3,20,200,"Enter Password" Con_Editpassword Edit2,160,200,100,20 Con_Button Exit_Button,200,250,"Quit",%111,0 End_Dialog Easy_Dialog Dialog1 Easy_Exit END |
6.3.3 Pop-up Menus A frequent opportunity offered to users is to choose from different options. This can be realized equally well with radio buttons but requires much more space if a larger number of objects are to be displayed. The utilization of button with a pop-up menu is a much better alternative. You can use the Control Library to equip traditional push buttons with pop-up menus as well as bevel buttons: |
Con_Popup R Con,X,Y[,W,H],T$,Mi Con_Popup R Con,X,Y,W,H,T$,F,Mi,Ma,Act |
Button with pop-up menu. |
Con_Bevelpopup R Con,X,Y[,W,H],T$,F,V,T Con_Bevelpopup R Con,X,Y,W,H,T$,F,V,Mi,Ma,T,Act |
Bevel button with pop-up menu. |
Before creating a button with pop-up menu, you have to use the functions
of the Menu Library to define a pop-up menu. Using Con_Popup requires that you pass the menu identification number in the parameter Mi. Ma is used in addition to specify the space to be taken up by the overall width of the pop-up title. Only W-Ma pixels remain then for the actual button. The title is always displayed to the left of the pop-up button, while the currently selected item is written to the button. Con_Bevelpopup offers more setting options than Con_Popup. With Con_Bevelpopup, bits 5 ,8, and 9 in F are also significant: Bit 5: If this bit is set, the pop-up arrow is centered vertically and displayed on the right side of the button, otherwise in the lower right corner. Bit 8: An item will not be marked with a checkmark when clicked. This means there are no different options from which to choose (e.g., font sizes) but a command is executed. The command execution itself has to be carried out by your program, of course. This behavior is symbolized by the pop-up menu only by not marking the selected item with a checkmark. The command operation type thus only serves a purpose if you also pass the address of an action function so that your program can react accordingly. This bit is evaluated only starting with System 8.1. Bit 9: Several items can be selected simultaneously (several checkmarks). Pop-up menus usually behave like radio buttons, i.e., only one item at a time is marked. Mi and Ma and T were already explained together with Con_Bevelbutton. The difference between Con_Popup and Con_Bevelpopup is that the latter always writes the text passed in T$ into the button and not to the left of it. The same applies to icons or pictures, which you can also assign to the bevel button. Con_Bevelpopup is available with System 8.0. |
Example: |
COMPILER "MIN_SIZE 1000000" COMPILER "BAS_MEM 1000000" COMPILER "Warnings off" Easy_Init 'Defines menu bar so that pop-up menus become functional. Def_Menu Menu_One,"Copyright",Copyright M_Title "File",File_Menu M_Entry "Quit/Q",Quit_Program End_Menu Def_Popup Currency M_Entry "Dollar",Dollar M_Entry "Euro",Euro M_Entry "Pound",Pound End_Popup Def_Dialog Dialog1,"Pop-up Buttons",1 'Push button with pop-up menu. Con_Popup Popup1,20,20,"Currency",Currency 'Bevel button with pop-up menu. Con_Bevelpopup Popup2,20,50,"Currency",1,Currency,1 'Bevel button with pop-up menu and multi-value behavior. 'Centered pop-up arrow. Con_Bevelpopup Popup3,20,80,"Currency",%1000100001,Currency,1 Con_Button Exit_Button,100,130,"Quit",%111,0 End_Dialog Easy_Dialog Dialog1 Easy_Exit END |
6.3.4 Scroll Bars and Sliders You already know scroll bars from the windows of the Window Library. As you know, EasyGem windows can be equipped with a horizontal and vertical scroll bar if so desired. These scroll bars are also controls, which are only automatically created and managed by EasyGem. The Control Library now offers you the possibility of defining your own scroll bars in any position within windows and dialog boxes. The following procedures are supplied for the scroll bars and the sliders, which behave similar: |
Con_Scrollbar R Con,X,Y,W,H,V,Mi,Ma Con_Scrollbar R Con,X,Y,W,H,F,V,Mi,Ma,Act |
Defines scroll bar. |
Con_Slider R Con,X,Y,W,H,V,Mi,Ma Con_Slider R Con,X,Y,W,H,F,V,Mi,Ma,T,Act |
Defines slider. |
Con_Littlearrows R Con,X,Y,V,Mi,Ma Con_Littlearrows R Con,X,Y,F,V,Mi,Ma,Act |
Defines little arrows. |
The first two control types differ from the ones discussed up to now
in that you always have to indicate the width and height of the control. This information
is then used to determine whether the scroll bar/slider is to be drawn horizontally
(W>H) or vertically
(W<H). You cannot pass a text for all three controls. Here, the parameters V, Mi, and Ma have their original significance. These controls do have a specific value, which depends on the position of the indicator. The initial value can be set with V while Mi/Ma sets the minimum/maximum possible value. All values have to be from the interval [-32768,32767]. The value range was extended to [-2147483648,2147483647] starting with System 8.5. Con_Littelarrows generates a scroll bar without indicator ("thumb"). This control then consists of only the two little arrows for scrolling up and down. The arrows are always positioned above one another and cannot be changed in size. This is why you do not have to specify the width and height. Starting with System 8.0, scroll bars and sliders also come equipped with "live feedback." This option automatically call the action function of the control when the user moves the indicator, which means your program can immediately react to the movement. Live feedback is active only if bit 1 from F is set. Otherwise, only the outer line is moved (ghost frame). |
With Con_Slider, the bits 2 - 4 used in F are as follows: Bit 2: The slider has so-called tick marks. These are small dashes located next to the slider (at the bottom or the right side). Bit 3: Attaches tick marks to the opposite side (top or left). Bit 4: The indicator is shaped like a rectangle (without tip pointing towards the tick marks). If this bit is set, bits 2 and 3 are ineffective and the slider is always depicted without the tick marks. T indicates the number of tick marks. In order for any tick marks to be displayed at all, the control rectangle (X,Y,W,H) has to be dimensioned large enough so that the tick marks fit into it and you need to set bit 2 for F as well. Attention: If the controls are aligned vertically, the value of the control for scroll bars increases the further down the slider is located. The exact opposite is true for sliders. Con_Scrollbar also functions with older Mac OS versions, however, without the live feedback feature, while Con_Slider and Con_Littelarrows are not available until System 8.0. |
Example: |
COMPILER "MIN_SIZE 1000000" COMPILER "BAS_MEM 1000000" COMPILER "Warnings off" Easy_Init Def_Dialog Dialog1,"Scroll bars and sliders",1 'Horizontal scroll bar. Con_Scrollbar Scroll1,20,20,160,16,0,-256,256 'Vertical scroll bar. Con_Scrollbar Scroll2,200,20,16,160,0,-256,256 'Horizontal slider. Con_Slider Slider1,20,50,160,16,0,0,512 'Horizontal slider with tick marks at bottom. Con_Slider Slider2,20,80,160,32,%101,0,0,9,10,0 'Horizontal slider with tick marks at top. Con_Slider Slider3,20,110,160,32,%1101,5,-10,10,21,0 'Vertical slider with angular indicator without tick marks. Con_Slider Slider4,230,20,16,160,%10001,3,0,10,0,0 'Little arrows. Con_Littlearrows Arrow1,30,150,0,0,10 Con_Button Exit_Button,160,200,"Quit",%111,0 End_Dialog Easy_Dialog Dialog1 Easy_Exit END |
A dialog box with different scroll bars and sliders operated in the usual manner opens when you start the sample program. Of course, this does not have any effect yet, because no action function has been defined as of yet. How to react sensibly to the actions of a user is illustrated further below. |
6.3.5 Progress Indicators These are elements used to indicate the progress for any long lasting operation. The progress indicators are divided into indeterminate indicators, which tell the user only that a operation with a longer duration is being carried out, and the determinate indicators, which inform the user continuously of the amount of work already finished. You can use the Control Library to define semiautomatically managed progress indicators, which keeps your programming work to a minimum: |
Con_Progressbar R Con,X,Y,W[,F,V,Mi,Ma] |
Defines progress bar. |
Con_Chasingarrows R Con,X,Y[,F] |
Defines control with asynchronous arrows. |
Progress bars have a fixed height and can be defined only horizontally.
That is the reason Con_Progressbar does not have a height parameter. An indeterminate progress bar is created
if the last four parameters are omitted. This type of progress bar has the appearance
of a rotating shaft and should always be used when the duration of an operation is
unknown. As illustrated further down, a special procedure can also be used to convert an indeterminate progress bar into a determinate one and vice versa. An indeterminate progress bar has the last four parameters set to F=1, V=-32768, Mi=-32768, Ma=32767 . The width for chasing arrows (asynchronous arrows) is also fixed, so that you need only indicate the position and the visibility flag, if needed. Neither one of the object has an action function, because they cannot be clicked on and are also not available until System 8.0. |
Example: |
COMPILER "MIN_SIZE 1000000" COMPILER "BAS_MEM 1000000" COMPILER "Warnings off" Easy_Init Def_Dialog Dialog1,"Progress indicators",1 'Indeterminate progress bar. Con_Progressbar Progress1,20,20,160 'Determinate progress bar. Con_Progressbar Progress2,20,50,160,1,100,0,1000 'Asynchronous arrows. Con_Chasingarrows Chasing1,20,80 Con_Button Exit_Button,100,120,"Quit",%111,0 End_Dialog Easy_Dialog Dialog1 Easy_Exit END |
The progress bar for this example shows a fixed progress value of 10%. Of course, an indeterminate progress bar makes sense only if the length of the bar can be adjusted to indicate the progress. Instructions on how to do that can be found further down. |
6.3.6 Icons and Pictures Icons and pictures can improve the layout of your dialog boxes and windows resulting in an easier to use and more clearly arranged user interface. The following procedures are used to display icons and pictures in dialog boxes and windows: |
Con_Icon R Con,X,Y,W,H,Mi,Ma Con_Icon R Con,X,Y,W,H,F,Mi,Ma,Act |
Defines icon. Source can also be a picture resource type 'PICT'. |
Con_Imagewell R Con,X,Y,W,H,Mi,Ma Con_Imagewell R Con,X,Y,W,H,F,Mi,Ma,Act |
Defines image well with picture or icon. |
The position as well as the desired width and height has to be specified
for all procedures. The picture or icon is then adapted to the specified format with
W and H. Icons with
image wells are not actually enlarged but displayed centered in the frame specified
with W and H. If an icon or image well is clicked, EasyGem usually calls your action function as soon as the mouse button has been pressed instead of waiting for the mouse button to be released over the object. So-called auto-tracking is activated if bit 1 is set with F. This means that the object is displayed highlighted in the case of Con_Icon, and that the action functions for the two object types are not called until the user releases the mouse button over the object. With Mi you can specify the resource type to be utilized: Mi = 1 : Icon suite resource (e.g., 'ICN#', 'ic14', 'ic18'). Mi = 2 : Individual icon resource type 'cicn'. Mi = 3 : Picture resource type 'PICT'. In contrast to the icon variation, this type has the advantage of not limiting pictures to any specific size. In Ma, you pass the resource ID of the desired object (icon suite, individual icon, or picture). Both objects are available starting with System 8.0. |
Example: |
COMPILER "MIN_SIZE 1000000" COMPILER "BAS_MEM 1000000" COMPILER "Warnings off" Easy_Init Def_Dialog Dialog1,"Icons and pictures",1 'Stop icon without auto-track. Con_Icon Icon1,26,20,32,32,2,0 'Note icon without auto-track. Con_Icon Icon2,76,20,32,32,2,1 'Caution icon without auto-track. Con_Icon Icon3,126,20,32,32,%11,2,2,0 'Image well with folder icon without auto-track. Con_Imagewell Image1,20,70,44,44,1,-3999 'Image well with disk icon without auto-track. Con_Imagewell Image2,70,70,44,44,1,-3998 'Image well with trash Icon and auto-track. Con_Imagewell Image3,120,70,44,44,%11,1,-3993,0 'Mac OS picture without auto-track. Con_Icon Pict1,180,20,100,100,3,-16506 Con_Button Exit_Button,80,140,"Quit",%111,0 End_Dialog Easy_Dialog Dialog1 Easy_Exit END |
Note: The sample program
uses resource numbers, which are associated with icons and pictures of the type 'PICT'
located in the system file. The system file is named "System," is located
in the system folder, and contains the operating system. All resources of the system
file are also accessible by other programs. All you have to do is indicate the corresponding
number. If you would like to get an overview of the available resources in the system file we recommend first making a copy to avoid any damage to the system file . Then open the copy with "ResEdit" or another resource editor. |
6.3.7 Time and Date Time and date displays are needed by many programs. We have implemented easy to use commands into the Control Library to be used to display or edit the time and date so that programmers do not repeatedly have to reinvent the wheel. These procedures are as follows: |
Con_Clock R Con,X,Y,F,T Con_Clock R Con,X,Y,W,H,F,T,Act |
Defines control with time or date. |
These procedures will depict a clock or the date in digital form.
Use the bits 1 and 2 in F
and four different variations (0<=T<=3) to generate displays with different properties : Let's start with F: Bit 1: If this bit is set, the display cannot be edited. Bit 2: This bit continuously updates the display. The clock thus matches the system clock. Indicate the following values for T: T=0 : Displays time in hours and minutes. T=1 : Displays time in hours, minutes, and seconds. T=2 : Displays date as day, month, year. T=3 : Displays date as month, year. Warning: Settings made to an editable display are immediately transferred to the system clock as soon as the user exits the display. It is best to have a look at the following example, which shows the individual variations. Time and date displays are available starting with System 8.0. |
Example: |
COMPILER "MIN_SIZE 1000000" COMPILER "BAS_MEM 1000000" COMPILER "Warnings off" Easy_Init Def_Dialog Dialog1,"Time and date",1 'Editable clock with hours and minutes without live time. Con_Clock Clock1,20,20,1,0 'Editable date with month and year without live time. Con_Clock Clock2,140,20,1,3 'Editable clock with hours, minutes, seconds, and live time. Con_Clock Clock3,20,60,%101,1 'Editable date with day, month, year, and live time. Con_Clock Clock4,140,60,%101,2 'Non-editable clock with hours, minutes, seconds, and live time. Con_Clock Clock5,20,100,%111,1 'Non-editable date with day, month, year, and live time. Con_Clock Clock6,140,100,%111,2 Con_Button Exit_Button,160,140,"Quit",%111,0 End_Dialog Easy_Dialog Dialog1 Easy_Exit END |
6.3.8 Miscellaneous Controls This chapter introduces three additional controls, which are not available until Mac OS 8.0 either: |
Con_Separator R Con,X,Y,W,H[,F] |
Defines a separator bar. |
Con_Popuparrow R Con,X,Y[,F],T,Act |
Defines a pop-up arrow. |
Con_Triangle R Con,X,Y[,F],V,T,Act |
Defines a disclosure triangle (small triangle rotating 90 degrees when clicked). |
Use Con_Separator to define a separator line to optimize the layout of your dialog boxes
and windows. If W>H,
the result is a horizontal separator line; otherwise a vertical line is drawn. The
width of the line is fixed, while the length can be determined with W or H. Con_Popuparrow generates an individual pop-up arrow. This arrow can be used to equip other controls with a pop-up menu. Of course, that pop-up menu has to be defined first and then called in your action function from the Menu Library with the command M_Show_Popup. The use of this control type makes thus only sense if you really have defined an action function, because nothing will happen otherwise when the user clicks on the pop-up arrow. Use T to select from eight different arrow types: T=0 : Large arrow pointing towards the right. T=1 : Large arrow pointing towards the left. T=2 : Large arrow pointing towards the top. T=3 : Large arrow pointing towards the bottom. T=4 : Small arrow pointing towards the right. T=5 : Small arrow pointing towards the left. T=6 : Small arrow pointing towards the top. T=7 : Small arrow pointing towards the bottom. |
Con_Triangle is used
to define small triangles with two states (V=0 or V=1).
You probably know these disclosure triangles from the Finder. In that case, there
always is a small triangle in front of the folders when selecting the list display
for the file depiction. The folder opens once you click on that triangle and all
of the files and subfolders contained in this folder are displayed below the file
name slightly indented to the right. The triangle itself is rotated 90 degrees. You can activate this automatic rotation for your own triangles by setting bit 1 of F. This activates the so-called auto-tracking and the triangle is displayed as automatically rotating by 90 degrees. When clicked again, the triangle returns to normal. Use T to specify the direction in which the normal triangle is to point (V=0): T=0 : Triangle points right. T=1 : Triangle points left. This is another control that makes sense only if a suitable action function has been defined, which actually carries out an operation, in this case the opening of something or another. All three controls are available starting with System 8.0. |
Example: |
COMPILER "MIN_SIZE 1000000" COMPILER "BAS_MEM 1000000" COMPILER "Warnings off" Easy_Init Def_Menu Menu_One," Copyright ",Copyright M_Title "File",File_Menu M_Entry "Quit/Q",Quit_Program End_Menu Def_Popup Text_Size M_Entry "8",Points_8 M_Entry "9",Points_9 M_Entry "10",Points_10 M_Entry "12",Points_12 M_Entry "14",Points_14 End_Popup Def_Dialog Dialog1,"Miscellaneous controls",1 'Vertical separator line. Con_Separator Separator1,140,10,4,80 Con_Edit Edit1,20,20,100,60,"This text can be edited." 'Large pop-up arrow pointing down. Con_Popuparrow Arrow1,90,90,3,&FN My_Popup(,) Con_Button Exit_Button,160,60,"Quit",%111,0 'Horizontal separator line. Con_Separator Separator2,10,100,230,4 'Disclosure triangle with auto-tracking 'Initial value to open, type right. Con_Triangle Triangle1,20,110,%11,1,0,&FN My_Disclosure(,) Con_Static Static1,40,110,"Additional options" Con_Checkbox Checkbox1,20,140,"Option 1",0 Con_Checkbox Checkbox2,20,160,"Option 2",0 End_Dialog Win_Getvirt Dialog1,0,Dialog1_W,Dialog1_H Easy_Dialog Dialog1 Easy_Exit END DEF FN My_Popup(Con,Part):LOCAL Item SELECT Con CASE Arrow1:M_Show_Popup Text_Size,MOUSEX,MOUSEY,Item END_SELECT END_FN DEF FN My_Disclosure(Con,Part):LOCAL W,H SELECT Con CASE Triangle1:Win_Getwork Dialog1,0,W,H IF H=Dialog1_H THEN Win_Setwork Dialog1,0,Dialog1_W,140 ELSE Win_Setwork Dialog1,0,Dialog1_W,Dialog1_H ENDIF END_SELECT END_FN |
A dialog box divided into three sections with two separator lines
opens after the start of the program. The upper left field shows an editable text
frame with a pop-up arrow pointing down. Once this arrow is clicked on, the action
function My_Popup
is called, which then takes over the display of the pop-up menu. However, selecting
certain text sizes does not yet have any effect on the displayed text, because this
would require procedures not discussed until later. The lower section shows an open disclosure triangle, which means it is pointing down. The two lower options can be hidden or displayed by clicking on this triangle. Note: The text behind the triangle would actually have to be switched between "more options" and "fewer options" as well. We omitted this here, because the procedures required for this have not yet been introduced. |
6.4 Control Groups Starting with Mac OS 8.0, it is possible to combine several controls in one control group. You are already familiar with one special group type from the Dialog Library. In that case, radio buttons located within the same line are automatically grouped together by EasyGem. Only then it is possible that all other buttons jump up when one of them is clicked. The buttons combined into a radio group thus have a behavior that depends on the other buttons. Mac OS 8.0 introduced additional group types, which enable a clearer layout for dialog boxes on the one hand, and facilitate the work of the programmer on the other, because it is now possible to use a single command to move an entire group or change its visibility status. |
6.4.1 Radio Groups and General Control Groups We begin with the following procedures to define radio groups as well as primary and secondary control groups: |
Con_Def_Radiogroup R Con,X,Y,W,H[,F] |
Initiates the definition of a radio group. |
Con_Def_Primgroup R Con,X,Y,W,H,T$[,V,T] Con_Def_Primgroup R Con,X,Y,W,H,T$,Mi,Ma,T Con_Def_Primgroup R Con,X,Y,W,H,T$,F,V,Mi,Ma,T,Act |
Starts the definition of a primary group. |
Con_Def_Secgroup R Con,X,Y,W,H,T$,T[,V,T] Con_Def_Secgroup R Con,X,Y,W,H,T$,Mi,Ma,T Con_Def_Secgroup R Con,X,Y,W,H,T$,F,V,Mi,Ma,T,Act |
Starts the definition of a secondary group. |
Con_End_Group |
Ends group definition. |
The rectangle defined with (X,Y,W,H) has to be specified for all group commands. This rectangle should be selected
in such a way as to fit all controls of a group into that rectangle. You should also
allow for a bit of surrounding space so that the individual controls do not stick
so close to the edge. Use Con_Def_Radiogroup to initiate the definition of a radio group. All subsequent Con_Radiobutton commands belong to this group. Bevel buttons may be used as well. Just set bit 4 of F when defining the bevel button. The individual buttons can be arranged any way desired. The definition is ended with Con_End_Group. Contrary to the radio group, primary and secondary groups are optically limited as well. Both group's behavior is identical, however, you should always use the primary group first and then only utilize the secondary groups if you need additional subgroups within the primary group. Use T to select from three group variations: T=0 : Only the text passed in T$ is displayed. T=1 : The group features a checkbox in its header as well. Use V to specify if the box is checked (0<=V<=1). T=2 : The group features a pop-up menu in its header as well. You have to pass the identification number of a pop-up menu in Mi, while Ma sets the width of the pop-up title. A group definition has to always end with Con_End_Group. The individual groups can also be nested. Group controls are available starting with System 8.0. |
Example: |
COMPILER "MIN_SIZE 1000000" COMPILER "BAS_MEM 1000000" COMPILER "Warnings off" Easy_Init Def_Menu Menu_One," Copyright ",Copyright M_Title "File",File_Menu M_Entry "Quit/Q",Quit_Program End_Menu Def_Popup Currency M_Entry "Dollar",Dollar M_Entry "Euro",Euro M_Entry "Yen",Yen M_Entry "Pound",Pound End_Popup Def_Dialog Dialog1,"Group Controls",1 'Primary group with title. Con_Def_Primgroup Prime1,20,20,100,90,"Color" 'Radio group embedded in primary group. Con_Def_Radiogroup Radio1,30,40,100,60 Con_Radiobutton Red,30,40,"Red" Con_Radiobutton Green,30,60,"Green" Con_Radiobutton Blue,30,80,"Blue" Con_End_Group Con_End_Group 'Primary group with checkbox. Con_Def_Primgroup Options,20,130,140,70,"Search options",1,1 Con_Checkbox Case_Sens,30,150,"Case sensitive",0 Con_Checkbox Wrap_Around,30,170,"Wrap around",1 Con_End_Group Con_Def_Primgroup Prime2,180,20,240,150,"Output" Con_Checkbox Vat,190,40,"Value added tax",1 'Secondary group with pop-up menu. Con_Def_Secgroup Sec1,200,70,200,80,"Currency",Currency,70,2 Con_Checkbox Roundings,210,100,"Rounding results",1 Con_Checkbox Separators,210,120,"Thousands separator",0 Con_End_Group Con_End_Group Con_Button Exit_Button,280,190,"Quit",%111,0 End_Dialog Easy_Dialog Dialog1 Easy_Exit END |
The example shows four control groups with one secondary group contained within a primary group. This example makes it easy to see the different variations (with text, checkbox, pop-up menu) and illustrates the optical difference between primary and secondary groups quite nicely. |
6.4.2 Placard Areas and Window Headers You are already familiar with the info line from the Window Library, which may be used to display text that remains separate and unaffected by the actual window content (e.g., the actual mouse coordinates). The Control Library now offers special controls, which serve no other purpose but to constitute a background for other objects. Basically, we are dealing here with control groups, too, because they start with a definition command and have to be concluded with Con_End_Group. The respective procedures are as follows: |
Con_Def_Placard R Con,X,Y,W,H[,F] |
Initiates the definition of a placard area. |
Con_Def_Header R Con,X,Y,W,H[,F],T |
Starts the definition of a window header. |
The control themselves have no functionality in either case. An area
with a border is drawn - nothing more. This area then has to be filled with additional
controls. Make sure that these controls are located within the predefined rectangle. With Con_Def_Header you can also use T to choose between two variations: T=0 : The window header has a thick, lower border line. T=1 : The window header has a thin, lower border line. This variation should be used to cascade several window headers. These are then separated by nothing more than a thin line, with the latter one is separated from the rest of the window with a thick line (T=0). Both controls are available starting with System 8.0. |
Example: |
COMPILER "MIN_SIZE 1000000" COMPILER "BAS_MEM 1000000" COMPILER "Warnings off" Easy_Init Def_Menu Menu_One," Copyright ",Copyright M_Title "File",File_Menu M_Entry "Quit/Q",Quit_Program End_Menu N$="Placard areas and window headers" K=%1100111111111111 Gwin_Open Win1,100,100,-320,-200,640,400,N$,"",K Win_Infoheight Win1,40 Win_Setflags Win1,%111:'Activate full redraw, do not clear background. Draw_Pattern Win1 Def_Controls Win1 Con_Def_Header Header1,0,0,656,20,1 Con_Static Static1,50,2,"Random pattern" Con_End_Group Con_Def_Header Header2,0,20,100,20,0 Con_Static Static2,20,22,"X= 0" Con_End_Group Con_Def_Header Header3,100,20,100,20,0 Con_Static Static3,120,22,"y= 0" Con_End_Group Con_Def_Header Header4,200,20,456,20,0 Con_End_Group Con_Def_Placard Placard1,20,60,130,100 Con_Bevelbutton Bevel1,30,70,"New pattern",1,1,&FN My_Action(,) Con_Static Static4,30,100,110,50,"Placard area for additional controls." Con_End_Group End_Controls M_Show Menu_One:'Display menu. REPEAT Ev_Msk=-1:Easy_Mesag Entry,Buffer$,Ev_Msk,Mx,My,Mb,Shift,Clicks,Kbrd IF Entry THEN SELECT Entry CASE Quit_Program,CVIL("quit"):Quit_Program CASE CVIL("oapp"):Win_Reopen Win1:'Open window after starting program. END_SELECT ELSE Win_Domessages Buffer$,&FN Close_Action() ENDIF UNTIL 0 'Generates Random Pattern. DEF PROC Draw_Pattern(Win):LOCAL X,Y,W,H Win_Getvirt Win,X,Y,W,H Gwin_Activate Win MODE =1:FILL STYLE =1,1 FOR J=Y TO Y+H-20 STEP 20 FOR I=X TO X+W-20 STEP 20 FILL COLOR =RND(256) PBOX I,J,20,20 NEXT I NEXT J Gwin_Disactivate END_PROC DEF FN My_Action(Con,Part) LOCAL Win=FN Win_Whichtop Draw_Pattern Win Win_Redraw Win END_FN DEF FN Close_Action(Win):LOCAL R=1 Easy_Alert 1,"[2][Do you really want|to exit the program?][Yes| No ]",R IF R=1 THEN Quit_Program ELSE RETURN 0 END_FN DEF PROC Quit_Program Easy_Exit :END END_PROC |
The example opens a graphics window and generates a random pattern
in this window. The info line is expanded to 40 pixels to accommodate all of the
window header controls. The window header controls are filled with static texts.
These can be modified later on during the program's runtime, e.g., to display the
current mouse position. The procedures required for this are discussed later. A placard area is created inside of the window. This area can contain additional controls (in this case a bevel button and a static text). Please make sure that controls located directly inside of the window are always displayed above the actual window content. This means that a part of the window content will always be hidden by these controls. It is thus recommended - except in a few special cases - to create the info line with a sufficient width first, followed by defining all of the window controls within the info line. However, if you still would like to define controls within the window, you always have to use Win_Setflags to modify the scroll behavior, because the controls would otherwise be shifted when scrolling. |
6.4.3 Tab Controls Tab Controls are a popular means for dividing the elements of a dialog box into different groups. The titles of all groups are then displayed in one row above the content area. Only one group is active at a time and only the controls of this active group are visible. Users can switch between the individual groups by clicking on the group titles. Tabs are also group controls, which contain the individual tab pages in the form of subgroups. The following procedures are available for defining tab controls: |
Con_Def_Tab R Con,X,Y,W,H,V,T Con_Def_Tab R Con,X,Y,W,H,F,V,T,Act |
Initiates the definition of a tab control. |
Con_Def_Tabgroup R Con,T$[,Ma] |
Starts the definition of a tab group. |
Con_End_Tab |
Ends the definition of a tab control. |
Con_Def_Tab already
determines the position and size of the tab including the tab page using (X,Y,W,H). You have to pass the
number of tab groups in V.
And finally, use T
to distinguish between two variations: T=0 : The titles of the tab groups are displayed in normal size. T=1 : The titles of the tab groups are displayed in a reduced size. You do not have to re-specify the size of the tab groups when using Con_Def_Tabgroup, because they are always displayed in the exact size needed to fit into the tab control area. T$ contains the title of the tab group and you have the option to pass the resource ID of a 'cicn' resource in Ma. This icon is then displayed in front of the text within the header. After calling Con_Def_Tabgroup, define all controls to be displayed within this group with the previously discussed commands. Then use Con_End_Group to finish the tab group definition. The entire tab control definition is concluded with Con_End_Tab. Tab controls are available starting with System 8.1. |
Example: |
COMPILER "MIN_SIZE 1000000" COMPILER "BAS_MEM 1000000" COMPILER "Warnings off" Easy_Init Def_Dialog Dialog1,-1,-1,320,290,"Tab Control",1 Con_Def_Tab Objects,4,4,300,200,3,0:'Tab with 3 tab groups, normal size. Con_Def_Tabgroup Buttons,"Buttons":'Button tab group. Con_Bevelbutton Bevel1,20,40,"Small bevel push button",%1,0,0 Con_Bevelbutton Bevel2,20,70,"Normal bevel toggle button",%1001,1,0 Con_Bevelbutton Bevel3,20,100,"Normal bevel sticky button",%10001,0,0 Con_Bevelbutton Bevel4,20,130,"Large bevel offset button",$401,0,0 Con_End_Group Con_Def_Tabgroup Texts,"Texts":'Text tab group. Con_Static Static1,20,40,"This is a static text without wrapping." Con_Static Static2,20,60,100,60,"This is a static text with wrapping." Con_Edit Edit1,20,120,270,60,"This text can be edited." Con_Static Static3,160,60,"Enter password:" Con_Editpassword Edit2,160,80,130,20 Con_End_Group Con_Def_Tabgroup Sliders,"Slider":'Slider tab group. Con_Slider Slider1,20,50,160,16,0,0,512 Con_Slider Slider2,20,80,160,32,%101,0,0,9,10,0 Con_Slider Slider3,20,110,160,32,%1101,5,-10,10,21,0 Con_Slider Slider4,230,40,16,150,%10001,3,0,10,0,0 Con_End_Group Con_End_Tab Con_Button Exit_Button,220,225,"Quit",%111,0 End_Dialog Easy_Dialog Dialog1 Easy_Exit END |
The program generates a tab control with three groups. Controls of a certain type are depicted in each group (bevel buttons, texts, and sliders). This serves only demonstration purposes. Of course, in practical application the groups would be divided according to intended use and not according to control type. |
6.5 Querying and Setting of Control Parameters |
6.5.1 Querying Basic Parameters Now that we have introduced all of the controls, we will explain how to query the standard parameters introduced at the beginning of the chapter. Sometimes one would like to know which checkboxes, radio buttons, etc. have been clicked or which texts the user has entered or the value of a slider after exiting a modal dialog box. The following procedures and functions are available for this purpose: |
Con_Getborder Con,R X,R Y[,R W,R H] Con_Getborder Con,0,R W,R H |
Query position and/or size of a control. |
FN Con_Gettext$(Con) |
Queries control text. |
FN Con_Getvalue(Con) |
Queries control value. |
FN Con_Getminimum(Con) |
Queries control minimum. |
FN Con_Getmaximum(Con) |
Queries control maximum. |
All of the procedures discussed here have to be passed the control
identification number of the control in Con if you would like to determine the corresponding parameters. EasyGem does
inform you about the control identification number when defining a control. Con_Getborder functions the same way as the procedure Win_Getborder, which you already know from the Window Library. The outer dimensions of the control are returned. This information is listed in local coordinates, that is relative to the upper left corner of the window, for which the control was defined. There are three variations of this command, which can be used to query only the position, the size, or all three together. If the control contains a text, this text can be determined with FN Con_Gettext$. For example, for all text controls but also for buttons, checkboxes, radio buttons, or tab groups. The current value of a control is ascertained with FN Con_Getvalue. This value can be only 0 (not selected) or 1 (selected) in the case of buttons, checkboxes, and radio buttons. Sliders, scroll bars, and progress bars, however, can accept maximum values of between -32768 and 32767, while the value is always 0 for most of the other controls (e.g., chasing arrows, window headers, and placard areas). Use FN Con_Getvalue to determine for pop-up menus, which menu items the user has selected. In this case, the position number (starting with 1) within the pop-up menu is returned. FN Con_Getminimum and FN Con_Getmaximum can be used with a purpose only for sliders, scroll bars, and progress bars. Use these functions to determine the limits offered to the user to set the controls. |
Example: |
COMPILER "MIN_SIZE 1000000" COMPILER "BAS_MEM 1000000" COMPILER "Warnings off" Easy_Init Def_Menu Menu_One," Copyright ",Copyright M_Title "File",File_Menu M_Entry "Modal dialog box",Modal_Dialog M_Line_Entry M_Entry "Quit/Q",Quit_Program End_Menu Def_Popup Currency M_Entry "Dollar",Dollar M_Entry "Euro",Euro M_Entry "Yen",Yen M_Entry "Pound",Pound End_Popup Def_Dialog Dialog1,"Query controls",1 Con_Checkbox Checkbox1,20,20,"Checkbox 1",1 Con_Checkbox Checkbox2,20,40,"Checkbox 2",0 Con_Static Static1,140,20,"Password:" Con_Editpassword Edit1,140,40,80,20 Con_Popup Popup1,20,70,"Currency:",Currency Con_Scrollbar Scroll1,20,110,160,16,0,-256,256 Con_Slider Slider1,20,140,160,32,%101,3,0,9,10,0 Con_Button Cancel_Button,20,190,"Cancel",%101,0 Con_Button Ok_Button,160,190," OK ",%111,&FN My_Action(,) End_Dialog 'Open text window for protocol purposes. Twin_Open Win1,20,41,-640,-400,80,100,"Protocol","",G_All M_Show Menu_One:'Displays menu. REPEAT Ev_Msk=-1:Easy_Mesag Entry,Buffer$,Ev_Msk,Mx,My,Mb,Shift,Clicks,Kbrd IF Entry THEN SELECT Entry CASE Quit_Program,CVIL("quit"):Quit_Program CASE Modal_Dialog,CVIL("oapp"):Easy_Dialog Dialog1 END_SELECT ELSE Win_Domessages Buffer$ ENDIF UNTIL 0 'This function is called when the user clicks on [ OK ]. DEF FN My_Action(Con,Part) Twin_Print Win1,"Checkbox 1 ="+STR$(FN Con_Getvalue(Checkbox1)) Twin_Print Win1,"Checkbox 2 ="+STR$(FN Con_Getvalue(Checkbox2)) Twin_Print Win1,"Password = "+FN Con_Gettext$(Edit1) Twin_Print Win1,"Currency ="+STR$(FN Con_Getvalue(Popup1)) Twin_Print Win1,"Slider bar ="+STR$(FN Con_Getvalue(Scroll1)) Twin_Print Win1,"Slider indicator ="+STR$(FN Con_Getvalue(Slider1)) Twin_Print Win1 END_PROC DEF PROC Quit_Program Easy_Exit :END END_PROC |
The program generates a modal dialog box with different controls.
If you are exiting the box by clicking on the [OK] button, then the My_Action function is called, which
is used to output the values or texts of the individual controls into the text window
opened at the start of the program. The menu can be used to reopen the dialog box and then the settings can be changed. |
6.5.2 Setting Basic Parameters Of course, it is not sufficient just to be able to query the values of a control, it also has to be possible to dynamically change them during the runtime of the program. For example, it is possible to set buttons or checkboxes in dependence of the actions of the user (selected or not selected) or to continuously update a progress button according to the progress of an operation. The following procedures are available for setting the standard parameters: |
Con_Setborder Con,X,Y[,W,H] Con_Setborder Con,0,W,H |
Sets position and/or size of a control. |
Con_Settext Con,T$ |
Sets control text. |
Con_Setvalue Con,V |
Sets control value. |
Con_Setminimum Con,Mi |
Sets control minimum. |
Con_Setmaximum Con,Ma |
Sets control maximum. |
Con_Setaction Con,Act |
Sets action function. |
Con_Setfontstyle Con,Fo,Si,Fa,Mo,Ju,Fc,Bc |
Sets font attributes. |
The first five procedures function here the same way as the corresponding
procedures and functions for querying the control parameters. Use Con_Setaction to subsequently change the action function of a control. This, however, should be required only for a few exceptional cases. Con_Setfontstyle will be discussed in more detail. This command has an effect on all controls containing a text. Use this command to subsequently change the text attributes. For example, use this to enlarge a static text and display it underlined so that it looks like a headline. The texts in the buttons should normally not be changed, so that the interface of your program corresponds with the settings of the Appearance Manager of the Mac OS. |
The parameters behind Con_Setfontstyle have the following meaning: Fo : Font identification
number (same meaning as with Set_Text_Font from the Extension Library).
|
Fc : Text color index (same
meaning as with Set_Text_Fore_Color from the Extension Library). Bc : Background color index (same meaning as with Set_Text_Back_Color from the Extension Library). Note: Should you not find a suitable color among the 256 colors offered by the Omikron Basic palette, you can modify any of these colors to a different hue or tint with Set_Indexed_Color from the Extension Library. Pass -1 as the parameter if the individual values are to remain unchanged. Warning: When you specify attributes with an enlarging effect, it can be that the text no longer fits into the control rectangle. In this case, you have to use Con_Setborder to enlarge the rectangle or specify a sufficiently large rectangle while defining it. Con_Setfontstyle is not available until System 8.0, while the remaining procedures in this chapter also function with older Mac OS versions. |
Example: |
COMPILER "MIN_SIZE 1000000" COMPILER "BAS_MEM 1000000" COMPILER "Warnings off" Easy_Init Def_Dialog Dialog1,"About this program",1 Con_Static Static1,20,20,100,30,"Copyright:" '14 points, bold, underlined, blue. Con_Setfontstyle Static1,-1,14,5,-1,-1,4,-1 Con_Static Static2,20,50,140,20,"Berkhan-Software" Con_Setfontstyle Static2,-1,-1,1,-1,-1,-1,-1:'Bold. Con_Static Static3,20,70,"Alt-Isehagen 19" Con_Static Static4,20,90,"29386 Hankensbuettel" Con_Static Static5,20,110,"Germany" Con_Button Ok_Button,150,160," OK ",%111,0 End_Dialog Easy_Dialog Dialog1 Easy_Exit END |
The program generates a modal dialog box with a very simple copyright message. Different style attributes and colors are used for the static texts. |
6.6 Procedures and Functions for Special Controls This chapter discusses the procedures and functions, which can be applied only to very special controls. An error message will be returned if these procedures and functions are used for control types that are not suitable. |
6.6.1 Bevel Buttons Let's begin with special commands for bevel buttons. These can contain icons in addition to the text as well. Use the following procedures to affect the position of text and graphic within a bevel button: |
Con_Settextpos Con,Ju,X |
Sets text alignment and text offset. |
Con_Setgrafpos Con,Ju,X,Y |
Sets graphics alignment and graphics offset. |
Con_Settextplace Con,Ju |
Sets text position relative to the graphic. |
Use Con_Settextpos to specify the inside display position of text associated with a bevel
button. Here, you can pass values between 0 and 3 in Ju: Ju=0 : Default direction of text Ju=1 : Centered Ju=2 : Left aligned Ju=3 : Right aligned. Use X to specify an additional horizontal offset, which is always calculated starting from the edge on which the text is bordering. The offset is ignored if the display is centered. |
Con_Setgrafpos functions
similarly as Con_Settextpos, with the difference that graphics in bevel buttons can be positioned vertically
as well. This is the reason additional value exist for Ju and you can pass a vertical offset in Y. Ju=0 : Default system direction Ju=1 : Centered Ju=2 : Left Ju=3 : Right Ju=4 : Top Ju=5 : Bottom Ju=6 : Left top Ju=7 : Left bottom Ju=8 : Right top Ju=9 : Right bottom |
Finally, use Con_Settextplace to set the position of the text relative to a simultaneously present graphic.
For this purpose you need to pass the following values in Ju: Ju=0 : Default system position Ju=1 : Normal position Ju=2 : To the right of the graphic Ju=3 : To the left of the graphic Ju=4 : Underneath the graphic Ju=5 : Above the graphic All three procedures are available starting with System 8.0. |
6.6.2 Text Controls Special procedures and functions are provided for text controls as well, which may be used. e.g., to mark a text section as a block or to find out in which text control the cursor is currently located. Some of these functions can be applied to other controls containing an editable text (e.g., clock controls). The following special functions are available for text controls: |
FN Con_Getkeyfocus(Win) |
Determines in which control the cursor is currently located. |
Con_Setkeyfocus Con |
Sets cursor in a specific control. |
Con_Clearkeyfocus Win |
Removes cursor. |
Con_Getselect Con,R S,R E |
Queries block. |
Con_Setselect Con,S,E |
Sets block. |
Con_Setkeyfilter Con,Fil |
Sets key filter function. |
First, we will explain the term "key focus" (or "keyboard
focus"). If a window contains controls that can be used to enter a text, one
of these controls can be distinguished from the others by having all keyboard input
focused on this control. This text control then has the "key focus." A control with key focus is recognizable by its blinking cursor. Starting with System 8.0, a colored border or focus ring surrounds the control as well. Use FN Con_Getkeyfocus to find out, which control in window Win has the key focus. This function returns a control identification number or 0, if no control in this window has the key focus. Con_Setkeyfocus sets the corresponding key focus to a specific control. You can use this command, e.g., to specify a specific text field for the input already when opening the dialog box. The contained text is then displayed already as selected. This procedure can be applied to editable text and clock controls. Con_Clearkeyfocus deletes the key focus in the window numbered Win. Of course, this can also be a dialog box. |
In case of editable text fields, the user can mark or highlight a
block. Use the procedure Con_Getselect to find out, which part of the text is marked. It returns the start or
end point of the marked text in S and E. The
count always starts with 0. Con_Setselect works completely analogously. Use it to mark a section of the text as a block by passing the start and end point of the desired range or area in S and E. If S and E are identical, then no block is displayed but the cursor is set to this position instead. |
A frequent problem is that not all characters are to be permissible
or valid for a specific input field. For example, the user should not be able to
enter any letters or special symbols of only numbers are fitting for a specific input
field. Use Con_Setkeyfilter to selectively control all input. For this purpose, you define a filter function and pass the address of this filter function to Con_Setkeyfilter using the variable Fil. The function has to be structured as follows: FN My_Keyfilter(Con,A,V,M) If the user now pushes a key and a filter function has been defined for the control with the key function, then this function is called, and Con is used to pass the control identification number, A to pass the ASCII code, V to pass the virtual key code, and M to pass the status of the modifier keys. Your function can now check whether the pressed key yields a valid character for this control or whether the character is to be converted to a different one (e.g., comma to period). Your function, however, has to always return the ASCII code of the desired character, or zero, if the pressed key is to be ignored. Of course, a filter function can be utilized for other purposes as well, e.g., to accept an entered value if the user pushes [Return] or to carry out cursor movements, which are not supported by the default settings. |
Example: |
COMPILER "MIN_SIZE 1000000" COMPILER "BAS_MEM 1000000" COMPILER "Warnings off" Easy_Init Def_Dialog Dialog1,"Editable texts",1 Con_Static Static1,20,20,"Only whole numbers" Con_Edit Edit1,160,20,80,20,"320" Con_Setkeyfilter Edit1,&FN My_Keyfilter(,,,) Con_Static Static2,20,50,"Fractions" Con_Edit Edit2,160,50,80,20,"-1.234" Con_Setkeyfilter Edit2,&FN My_Keyfilter(,,,) Con_Static Static3,20,80,"Max. 10 letters" Con_Edit Edit3,160,80,80,20,"XYZ" Con_Setkeyfilter Edit3%L,&FN My_Keyfilter(,,,) Con_Button Execute,160,120," OK ",%111,0 End_Dialog Con_Setkeyfocus Edit1:'Sets key focus to first text field. Easy_Dialog Dialog1 Easy_Exit END DEF FN My_Keyfilter(Con,A,V,M):LOCAL R SELECT Con CASE Edit1:'Permit only numbers. IF A>=48 AND A<=57 THEN R=A ELSE R=0 CASE Edit2 SELECT A CASE 43,45,46,48 TO 57 R=A:'Permit plus, minus, decimal point, and numbers. CASE 44:R=46:'Change comma to period. DEFAULT :R=0 END_SELECT CASE Edit3 IF LEN(FN Con_Gettext$(Edit3))<10 THEN 'Permit maximal 10 characters. SELECT A CASE 65 TO 90:R=A:'Permit upper case letters. CASE 97 TO 122:R=A-32:'Change lower case to upper case. DEFAULT :R=0 END_SELECT ELSE R=0 ENDIF END_SELECT RETURN R DEF PROC Quit_Program Easy_Exit :END END_PROC |
The program illustrates how to use key filter functions to individually
affect text field input. Another example is listed in Chapter 3.5. It shows how to use the here introduced functions and procedures to realize the standard functions of the edit menu. |
6.6.3 Progress Bars Chapter 6.3.5 introduced the progress bars available starting with System 8.0. In practice, however, the duration of any process or operation is often hard to predict or estimate. This is best expressed by converting a determinate progress bar to an indeterminate one. The following are used for converting between the two states: |
FN Con_Getprogressbar(Con) |
Determines whether the progress bar is a determinate or an indeterminate progress bar. |
Con_Setprogressbar Con,M |
Switches between determinate and indeterminate progress bar. |
FN Con_Getprogressbar
returns the function value zero (0), if the progress bar is in an determinate state;
otherwise, one (1) is returned. Switch between the two types accordingly using Con_Setprogressbar. M=0 : determinate M=1 : indeterminate Both statements are not available until System 8.0. |
6.6.4 Scroll Bars and Sliders The user can change the control value for scroll bars and sliders in a variety of different ways. On the one hand, it is possible to grasp and move the indicator with the mouse, on the other it is also possible to click on the arrows or the area next to the indicator. This then changes the control value by previously set fixed increments. The following procedures are offered to query or set these values: |
Con_Getstep Con,R S1,R S2 |
Queries increments. |
Con_Setstep Con,S1,S2 |
Sets increments. |
FN Con_Getviewsize(Con) |
Queries indicator size. |
Con_Setviewsize Con,S |
Sets indicator size. |
S1 and S2 have the following meanings in this case: S1 : Increment to be used when clicking on the arrows. S2 : Increment to be used when the user clicks next to the indicator. Con_Getstep and Con_Setstep can be used only for scroll bars and slider, an error message is returned otherwise. Mac OS 8.5 now offers proportional scroll bars. A proportional scroll bar no longer has a constant indicator size but the indicator can be adjusted in size to fit the ratio of displayed to overall existing data. You might have already observed this type with some of the EasyGem windows. In this case, the size of the indicator for the horizontal and vertical scroll bars is automatically adjusted by EasyGem to fit the ratio of sectional view to virtual window size, which offers users an immediate visual representation of how much data are virtually still present. The same is now possible for your own scroll bars with Con_Setviewsize. For example, if you use H_Work to display the height visible on screen and H_Virt to display the virtual data amount, you have to set S=H_Work(Ma-Mi)\(H_Virt-H_Work) with Ma being the maximum and Mi the minimum control value. This formula is much simplified if you always specify Ma=H_Virt-H_Work and Mi=0. This also applies to S=H_Work. Warning: If H_Virt=H_Work, then you may not use this formula (division by zero). Instead, use Con_Deactivate to deactivate the scroll bar. Use FN Con_Getviewsize to query the current setting. Both statements work only with scroll bars and are not available until System 8.5. |
6.6.5 Time and Date Displays The Control Library does indeed offer the possibility to define different time and date display variations. Of course, these displays should then also be adjustable to reflect a specific time or date or it should be possible to query them for the current settings. Two procedures exist for this purpose: |
Con_Getclock Con,R H,R M,R S,R D,R Mo,R Y |
Queries time and date. |
Con_Setclock Con,H,M,S,D,Mo,Y |
Sets time and date. |
The parameters have the following meanings: H : Hour (0<=H<=23). M : Minute (0<=M<=59). S : Second (0<=S<=59). D : Day. Mo : Month. Y : Year (-30081<=Y<=29940). Both procedures may use only time and date displays and are available starting with System 8.0. |
6.6.6 Menus The next items are controls with pop-up menus. Here, we need a function to determine, which pop-up item has been clicked on last. It should also be possible to assign a different pop-up menu to a control during the runtime of the program. Both objectives are covered in the Control Library with suitable statements: |
FN Con_Getmenuentry(Con) |
Queries which menu item was last clicked. |
Con_Setmenu Con,Id |
Assigns pop-up menu. |
You have to pass the menu identification number of a pop-up menu in
Id, which, of course, has
to be defined first. Both statements may be used only for standard pop-up buttons and bevel buttons with pop-up menus. FN Con_Getmenuentry for bevel buttons is available starting with System 8.0, while System 8.1 is required by Con_Setmenu. |
6.6.7 Icons and Pictures Previously, when working with the Finder, you have probably already noticed that one and the same icon can be depicted quite differently. For example, an open folder looks different than a closed or selected one. This so-called transform behavior can be set or queried with two statements from the Control Library: |
FN Con_Gettransform(Con) |
Queries transform mode. |
Con_Settransform Con,T |
Sets transform mode. |
The following variable types are possible for the transform mode: T=$1 : Nonselectable (disabled). T=$2 : Offline. T=$3 : Open. If the value $4000 is added to each of the three values, then the object is selected additionally. It is also possible to add $100 to $700. Then the object takes on the color as the label color for folders and files, which was previously set in the Finder. For example: T=$4203 has the effect that the object is depicted as open, selected, and with the label color 2. Both statements may be used only for controls of the bevel button type, image wells, and icons, and are not available until System 8.0. |
6.6.8 Bevel Button, Image Well, and Tab Group Contents Some controls can contain an icon or picture in addition to a text. Use this procedure to exchange the content during the runtime of your program: |
Con_Setcontent Con,T,Id |
Sets control content. |
In this case, the parameter T determines the form of the new content, while the number of the desired
resource is passed in Id: T=1 : Id contains the number of an icon suite resource (e.g., 'ICN#', 'ic14', 'ic18'). T=2 : Id contains the number of an individual icon resource type 'cicn'. T=3 : Id contains the number of a picture resource type 'PICT'. Use this procedure to change the content of bevel buttons, image wells, and tab groups (only icon in header). System 8.0 suffices for bevel buttons and image wells, while tab groups require System 8.1. |
Example: |
COMPILER "MIN_SIZE 1000000" COMPILER "BAS_MEM 1000000" COMPILER "Warnings off" Easy_Init 'Define menu bar so that pop-up menus become functional. Def_Menu Menu_One," Copyright ",Copyright M_Title "File",File_Menu M_Entry "Quit/Q",Quit_Program End_Menu Def_Popup Icons M_Entry "Trash",Trash M_Entry "Program",Program M_Entry "Floppy Disk",Floppy_Disk M_Entry "Folder",Folder M_Entry "File",File End_Popup Def_Popup Transfers M_Entry "Normal",Normal M_Entry "Offline",Offline M_Entry "Disabled",Disabled M_Entry "Opened",Opened End_Popup Def_Popup Labels M_Entry "No Label",No_Label M_Entry "Label 1",Label1 M_Entry "Label 2",Label2 M_Entry "Label 3",Label3 M_Entry "Label 4",Label4 M_Entry "Label 5",Label5 M_Entry "Label 6",Label6 M_Entry "Label 7",Label7 End_Popup My_Action=&FN My_Action(,) Def_Dialog Dialog1,"Icon Transfer Modes",1 Con_Bevelpopup Popup1,20,20,140,20,"Icon Suites",1,Icons,0,0,1,My_Action Con_Checkbox Checkbox1,20,50,140,20,"Selected",1,0,My_Action Con_Bevelpopup Popup2,20,80,140,20,"Transfer modes",1,Transfers,0,0,1,My_Action Con_Bevelpopup Popup3,20,110,140,20,"Labels",1,Labels,0,0,1,My_Action Con_Imagewell Image1,180,20,100,100,1,1,-3993,0:'Trash. Con_Button Exit_Button,200,160,"Quit",%111,0 End_Dialog Easy_Dialog Dialog1 Easy_Exit END 'This program uses a shared action function for 'several controls. The distinction is made via the control 'identification number in con. DEF FN My_Action(Con,Part):LOCAL A,B SELECT Con CASE Popup1:'Here, a switch from one icon to the next is executed. A=FN Con_Getmenuentry(Popup1) SELECT A CASE Trash:Con_Setcontent Image1,1,-3993 CASE Program:Con_Setcontent Image1,1,-3996 CASE Floppy_Disk:Con_Setcontent Image1,1,-3998 CASE Folder:Con_Setcontent Image1,1,-3999 CASE File:Con_Setcontent Image1,1,-4000 END_SELECT CASE Checkbox1:'Immediately analyze the checkbox status. A=FN Con_Getvalue(Checkbox1):B=FN Con_Gettransform(Image1) IF A THEN Con_Settransform Image1,B OR $4000 ELSE Con_Settransform Image1,B AND NOT $4000 ENDIF CASE Popup2:'Change only the transform mode. A=FN Con_Getmenuentry(Popup2):B=FN Con_Gettransform(Image1) SELECT A CASE Normal:Con_Settransform Image1,B AND $FFF0 CASE Offline:Con_Settransform Image1,B AND $FFF0 OR $1 CASE Disabled:Con_Settransform Image1,B AND $FFF0 OR $2 CASE Opened:Con_Settransform Image1,B AND $FFF0 OR $3 END_SELECT CASE Popup3:'Change only the label. A=FN Con_Getmenuentry(Popup3):B=FN Con_Gettransform(Image1) SELECT A CASE No_Label:Con_Settransform Image1,B AND $F0FF CASE Label1:Con_Settransform Image1,B AND $F0FF OR $100 CASE Label2:Con_Settransform Image1,B AND $F0FF OR $200 CASE Label3:Con_Settransform Image1,B AND $F0FF OR $300 CASE Label4:Con_Settransform Image1,B AND $F0FF OR $400 CASE Label5:Con_Settransform Image1,B AND $F0FF OR $500 CASE Label6:Con_Settransform Image1,B AND $F0FF OR $600 CASE Label7:Con_Settransform Image1,B AND $F0FF OR $700 END_SELECT END_SELECT END_FN DEF PROC Quit_Program Easy_Exit :END END_PROC |
Use the first pop-up menu to select among the different icons the
ones to be displayed in the image well. The checkbox and other pop-up menus permit
the setting of different transfer modes. A shared action function is used to immediately realize the changes made by the user. Note: The sample program uses icon suite resource numbers, which are located in the system file. The system file is named "System," is located in the system folder, and contains the operating system. All resources of the system file are also accessible by other programs. All you have to do is indicate the corresponding number. If you would like to get an overview of the available resources in the system file we recommend first making a copy to avoid any damage to the system file . Then open the copy with "ResEdit" or another resource editor. |
6.7 Control Display From the Menu Library you are already familiar with the option of disabling an item that is not to be selected. The same possibility exists for controls. Moreover, there are additional display options for controls, which can be set with the following procedures: |
Con_Show Con |
Renders control visible. |
Con_Hide Con |
Hides control. |
Con_Activate Con |
Activates control (renders it selectable). |
Con_Deactivate Con |
Deactivates control (renders it nonselectable). |
Con_Hilite Con,Part |
Emphasizes control or a part of the control. |
The first four procedures are essentially self-explanatory, however,
the parameter Part
with Con_Hilite
requires some more detailed explanation. This parameter is used to pass the so-called
part code, which determines which part of the control is emphasized or which depiction
form or style is to be selected. The following values are possible for Part: Part=0 : No part (control is displayed normal). Part=1 : Label (header for tab groups). Part=2 : Menu. Part=4 : Triangle (disclosure triangle). Part=5 : Editable text. Part=6 : Picture. Part=7 : Icon. Part=8 : Time and date displays. Part=10 : Button. Part=11 : Checkbox. Part=12 : Radio button. Part=20 : Arrow up or to the left (in case of scroll bars and small arrows). Part=21 : Arrow down or to the right (in case of scroll bars and small arrows). Part=22 : Page up or to the left (in case of scroll bars and sliders). Part=23 : Page down or to the right (in case of scroll bars and sliders). Part=26 : Image well. Part=27 : Radio group. Part=129 : Indicator (in case of scroll bars and sliders). Part=255 : Not selectable (disabled). Part codes 0 and 255 have the same effect as Con_Activate and Con_Deactivate. You can use these to disable certain controls in your dialog box (rendering them nonselectable), because they might currently not fulfill any practical purpose. Note: The part code is also returned in the second parameter of an action function defined by you. This can be used to determine, e.g., if the user has clicked on the arrows or the "thumb" of a scroll bar. |
Example: |
COMPILER "MIN_SIZE 1000000" COMPILER "BAS_MEM 1000000" COMPILER "Warnings off" Easy_Init Def_Dialog Dialog1,"Control Display",1 Con_Def_Primgroup Prime1,20,20,200,90,"Existing functions" Con_Bevelbutton Bevel1,40,40,"Function 1",1,1,0 Con_Bevelbutton Bevel2,40,70,"Function 2",1,1,0 Con_End_Group Con_Def_Primgroup Prime2,20,130,200,90,"Planned functions" Con_Bevelbutton Bevel3,40,150,"Function 3",1,1,0 Con_Bevelbutton Bevel4,40,180,"Function 4",1,1,0 Con_End_Group Con_Deactivate Prime2:'Deactivate second group together with entire content. Con_Button Exit_Button,140,240,"Quit",%111,0 End_Dialog Easy_Dialog Dialog1 Easy_Exit END |
The dialog box contains two groups with two bevel buttons each. Both of these buttons symbolize functions, which are not included in the current version yet but are planned for future versions. They are thus disabled and cannot be selected. Please note that the entire content is deactivated together with the group's deactivation. |
6.8 Miscellaneous Control Functions This chapter introduces a few additional procedures and functions, which might be useful for advanced users. They are as follows: |
Con_Find Win,X,Y,R Con,R Part |
Determines control identification number and part code. |
Con_Redraw Con |
Redraws control. |
Con_Dispose Con |
Deletes control. |
FN Con_Handle(Con) |
Determines control handle. |
Let's start with Con_Find. This procedure makes it possible to determine whether the window Win contains a control located
at (X,Y). If this
is the case, the control identification numbers and the part code are returned. Both
values equal zero otherwise. The position has to be in local coordinates of the to
be searched window. Use Con_Redraw to redraw only a certain, individual control. EasyGem usually takes care of the redraw, so that this command is usually utilized only in exceptional cases. The same applies to Con_Dispose. If a window is closed, EasyGem automatically deletes the controls defined for this window and thus releases the memory used by these controls. This function FN Con_Handle is only of interest to pros. It returns the control handle specified by the Mac OS. Use this to directly apply the functions of the Mac OS to the EasyGem controls as well. A detailed description about the Mac OS functions for controls can be found in "Inside Macintosh, Macintosh Toolbox Essentials" and "Inside Macintosh, Control Manager." |
Remember to have a look at the "StarrySky.BAS" program in the DEMO folder. Among others, it illustrates how to use the mouse during the runtime of the program to move controls within the window. |
|
© 1998-2004 Berkhan-Software www.berkhan.de | Home |