Reference List Utility Library -turn page-Reference List Control Library

Contents| Start

The Control Library


6.The Control Library
General 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
Icons and Pictures
Bevel Button, Image Well, and Tab Group Contents
Control Display
Other Control Functions
Reference 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.
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.
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.
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

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.

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:

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.

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 "Warnings off"

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

Twin_Open Win1,20,41,-640,-400,80,24,"Protocol","",G_All:'Open Text Window.
Easy_Dialog Dialog1

DEF FN My_Action(Con,Part)
  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."
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.
COMPILER "Warnings off"

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
Easy_Dialog Dialog1

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.

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.

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.
COMPILER "Warnings off"

'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
Def_Popup Currency
 M_Entry "Dollar",Dollar
 M_Entry "Euro",Euro
 M_Entry "Pound",Pound

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
Easy_Dialog Dialog1

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.
COMPILER "Warnings off"


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
Easy_Dialog Dialog1
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.
COMPILER "Warnings off"


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
Easy_Dialog Dialog1
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.

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.

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.
COMPILER "Warnings off"


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
Easy_Dialog Dialog1
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

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=0 : Displays time in hours and minutes.
T=1 : Displays time in hours, minutes, and seconds.
T=2 : Displays date as day, month, year.
: 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.
COMPILER "Warnings off"


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
Easy_Dialog Dialog1

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.

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.

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.
COMPILER "Warnings off"

Def_Menu Menu_One," Copyright ",Copyright
 M_Title "File",File_Menu
 M_Entry "Quit/Q",Quit_Program
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

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
Win_Getvirt Dialog1,0,Dialog1_W,Dialog1_H
Easy_Dialog Dialog1

DEF FN My_Popup(Con,Part):LOCAL Item
  CASE Arrow1:M_Show_Popup Text_Size,MOUSEX,MOUSEY,Item
DEF FN My_Disclosure(Con,Part):LOCAL W,H
  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
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.
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.

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.

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.
COMPILER "Warnings off"

Def_Menu Menu_One," Copyright ",Copyright
 M_Title "File",File_Menu
  M_Entry "Quit/Q",Quit_Program
Def_Popup Currency
 M_Entry "Dollar",Dollar
 M_Entry "Euro",Euro
 M_Entry "Yen",Yen
 M_Entry "Pound",Pound

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"
 '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_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_Button Exit_Button,280,190,"Quit",%111,0
Easy_Dialog Dialog1
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

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.

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.
COMPILER "Warnings off"

Def_Menu Menu_One," Copyright ",Copyright
 M_Title "File",File_Menu
  M_Entry "Quit/Q",Quit_Program
N$="Placard areas and window headers"
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_Def_Header Header2,0,20,100,20,0
  Con_Static Static2,20,22,"X= 0"
 Con_Def_Header Header3,100,20,100,20,0
  Con_Static Static3,120,22,"y= 0"
 Con_Def_Header Header4,200,20,456,20,0
 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."

M_Show Menu_One:'Display menu.
 Ev_Msk=-1:Easy_Mesag Entry,Buffer$,Ev_Msk,Mx,My,Mb,Shift,Clicks,Kbrd
 IF Entry
   SELECT Entry
    CASE Quit_Program,CVIL("quit"):Quit_Program
    CASE CVIL("oapp"):Win_Reopen Win1:'Open window after starting program.
  ELSE Win_Domessages Buffer$,&FN Close_Action()

'Generates Random Pattern.
DEF PROC Draw_Pattern(Win):LOCAL X,Y,W,H
 Win_Getvirt Win,X,Y,W,H
 Gwin_Activate Win
 FOR J=Y TO Y+H-20 STEP 20
  FOR I=X TO X+W-20 STEP 20
   PBOX I,J,20,20
DEF FN My_Action(Con,Part)
 LOCAL Win=FN Win_Whichtop
 Draw_Pattern Win
 Win_Redraw Win
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
DEF PROC Quit_Program
 Easy_Exit :END
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.
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

Tab controls are available starting with System 8.1.
COMPILER "Warnings off"

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_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_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_Button Exit_Button,220,225,"Quit",%111,0
Easy_Dialog Dialog1
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.

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).
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.
COMPILER "Warnings off"

Def_Menu Menu_One," Copyright ",Copyright
 M_Title "File",File_Menu
  M_Entry "Modal dialog box",Modal_Dialog
  M_Entry "Quit/Q",Quit_Program
Def_Popup Currency
 M_Entry "Dollar",Dollar
 M_Entry "Euro",Euro
 M_Entry "Yen",Yen
 M_Entry "Pound",Pound
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(,)
'Open text window for protocol purposes.
Twin_Open Win1,20,41,-640,-400,80,100,"Protocol","",G_All

M_Show Menu_One:'Displays menu.
 Ev_Msk=-1:Easy_Mesag Entry,Buffer$,Ev_Msk,Mx,My,Mb,Shift,Clicks,Kbrd
 IF Entry
   SELECT Entry
    CASE Quit_Program,CVIL("quit"):Quit_Program
    CASE Modal_Dialog,CVIL("oapp"):Easy_Dialog Dialog1
  ELSE Win_Domessages Buffer$

'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

DEF PROC Quit_Program
 Easy_Exit :END
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.

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).
Note: If you do not know this number but just the font name, you can use the function FN Get_Font_Number from the Extension Library to determine the font identification number.
Si : Font size in points (same meaning as with Set_Text_Size from the Extension Library).
Fa : Font style (same meaning as with Set_Text_Face from the Extension Library)
: Display mode (same meaning as with Set_Text_Mode from the Extension Library).
Ju : Text alignment. You can set the following values for Ju:

Ju=0 : Default direction of text
Ju=1 : Centered
Ju=2 : Left aligned
Ju=3 : Right aligned

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.
COMPILER "Warnings off"

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
Easy_Dialog Dialog1
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.

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.

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.
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.
COMPILER "Warnings off"

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
Con_Setkeyfocus Edit1:'Sets key focus to first text field.
Easy_Dialog Dialog1

DEF FN My_Keyfilter(Con,A,V,M):LOCAL R
  CASE Edit1:'Permit only numbers.
   IF A>=48 AND A<=57 THEN R=A ELSE R=0
  CASE Edit2
    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
  CASE Edit3
   IF LEN(FN Con_Gettext$(Edit3))<10
    THEN 'Permit maximal 10 characters.
      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
    ELSE R=0
DEF PROC Quit_Program
 Easy_Exit :END
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

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.

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.
COMPILER "Warnings off"

'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
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
Def_Popup Transfers
 M_Entry "Normal",Normal
 M_Entry "Offline",Offline
 M_Entry "Disabled",Disabled
 M_Entry "Opened",Opened
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

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
Easy_Dialog Dialog1

'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
  CASE Popup1:'Here, a switch from one icon to the next is executed.
   A=FN Con_Getmenuentry(Popup1)
    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
  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
  CASE Popup2:'Change only the transform mode.
   A=FN Con_Getmenuentry(Popup2):B=FN Con_Gettransform(Image1)
    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
  CASE Popup3:'Change only the label.
   A=FN Con_Getmenuentry(Popup3):B=FN Con_Gettransform(Image1)
    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
DEF PROC Quit_Program
 Easy_Exit :END
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.

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=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).
: 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.
COMPILER "Warnings off"

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_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_Deactivate Prime2:'Deactivate second group together with entire content.
Con_Button Exit_Button,140,240,"Quit",%111,0
Easy_Dialog Dialog1
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.

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.

Reference List Utility Library -turn page- Reference List Control Library

Contents | Start

© 1998-2000 Berkhan-Software | Home