Graphical User Interface Canvas Frame Event structure Platform-free GUI operations Operator << Operator >> Operator = Operator ~ Operator + Operator

Transcription

1 Graphical User Interface Canvas Frame Event structure Platform-free GUI operations Operator << Operator >> Operator = Operator ~ Operator + Operator - Operator [] Operator size Operator $ Operator? Operator! Operator ^ Operator & Message Boxes GUI Maker Tool Resource Menu Item Canvas Menu Item Palette Menu Item Platform Menu Item Palette Selections Moving a control Editing a GroupBox Manual Editing Z++ canvas identifier Files created by GUI Maker Folder Arrangement for Resources Tab Order Actual size of text on target device Menu Resource Generated Header File (Menu) Programming Menu Commands Operators for Menu Items

2 Graphical User Interface User interaction with a device depends on the device capabilities. However, graphical user interface (GUI) has matured and can be dealt with as an abstraction. Z++ GUI presentations are created with drag-and-drop tools that come with Z++ Visual. All new additions to PDA and cell-phones, such as navigation buttons, cameras and the input buttons and switches can be easily abstracted and generalized. A vendor supplied SDK that works for a specific device is required for developing system-programming tools, such as Z++ Visual. There is no reason for application developers to specialize in the use of vendor supplied system tools, which demand an up-to-date intimate familiarity with the device, the SDK, the libraries and the dialect of the language supported by the vendor. Z++ has no dialects, and is exactly the same for all devices and platforms supported by them. This section illustrates the notions of canvas and frame, and their relationship. The abstract picture is quite simple. Z++ graphical user interface is object-oriented and will be explained after introducing the notions of canvas, frame and events. Canvas The GUI-Maker tool generates a Z++ canvas for inclusion in source files. Following is an example of a Z++ canvas generated by the GUI Maker. An engineer designs a canvas via the GUI-Maker. There is no Z++ statements relevant to drawing the GUI objects. canvas MyCanvas Button Done; Button Next; Field Text; ComboBox Values; GroupBox Choices; RadioButton Yes; RadioButton No; end; The types of GUI entities, such as Button, are not Z++ types. They only have a meaning within the context of a generated canvas. The identifiers, such as Done, are used in sending messages to the GUI entities. There are no C-like defines in Z++. Frame The Z++ class type constructor for GUI is called frame. The frame provides functionality through its methods. The syntax for defining a frame is identical to a class with two differences. A frame must be associated with a canvas, and must have an instinct method, as illustrated below.

3 frame MyFrame := MyCanvas // members and methods public: $MyFrame(interfaceEventType&); // instinct method // other methods end; In this example, the frame MyFrame is associated to the canvas MyCanvas, via the association operator := (colon followed by equal sign). We will discuss the semantics of this association as we proceed. The instinct method of a frame has the same name as the frame, and its name is preceded with the $ symbol. The argument to the instinct method is always a reference to interfaceeventtype, which we discuss next. Event structure The following types are defined in Z++ system header file interface.h. enum interfaceeventsignals { _IES_Draw_Signal, _IES_Erase_Signal, _IES_Pen_Tap_Signal, _IES_Mouse_Click_Signal, // other events follow }; struct interfaceeventtype ushort x; ushort y; ushort entity; interfaceeventsignals Event; end; The structure interfaceeventtype is the type of argument passed to the instinct method of a frame. Generally, a Z++ program only uses the members entity and Event of the event structure. The x and y coordinates of an event are used internally by the Z47 processor. The argument to the instinct method is supplied by the Z47 processor, which also invokes the instinct method of the frame that has received an event. Below is an illustration of an instinct method for our example frame MyFrame.

4 MyFrame::$MyFrame(interfaceEventType& event) switch(event.event) case _IES_Draw_Signal: // initializations, etc. case _IES_Mouse_Click_Signal: select(event.entity) case Done: // processing code case Text: // processing code case Yes: // processing code end; endswitch; endselect; The pattern for the body of an instinct method is quite intuitive. There is a switch over the Event, and for each case of the switch, one can have a select statement over the entities in the canvas associated with the frame. In this example, the event _IES_Draw_Signal is handled directly, while the event _IES_Mouse_Click_Signal is handled for several entities in the canvas. The select statement can only appear in an instinct method of a frame, and its case labels are names of entities in the canvas associated with the frame.

5 Platform-free GUI operations Z++ GUI operations are universally valid regardless of platform. In addition, Z++ compiler verifies the validity of operations and types of operands. GUI operations are directly supported as opposed to indirectly via libraries. The operations are presented in the form of operators rather than long library function names taking a list of arguments. Remark. In methods of a frame associated to a canvas one refers to the entities in the canvas using the operator :: (colon followed by another colon). For instance, MyCanvas::Done refers to the Button named Done in MyCanvas. The following list presents the Z++ GUI operations. Operands can be constants, such as string literals, or Z++ objects. Operator << The Z++ output operator allows writing to GUI entities, as well. This operator can be applied to several GUI entities. An example of syntax is MyCanvas::Yes << True. Label. Rewrites the statement showing in the label area. Button. Rewrites the name showing on the button. Field. Appends new text to the contents of a text area. ComboBox. Takes a numeric argument and sets the current selection. RadioButton and CheckBox. Take a boolean and set the button accordingly. Operator >> The input operator does the opposite of output operator << in that it retrieves the values associated with the GUI elements and puts them in a Z++ object. For instance, a RadioButton reports True/False based on its state (checked or unchecked). Operator = The assignment operator sets new values. For instance, the statement MyCanvas::Text = Hello World! ; writes the string to the field Text. Unlike operator << the assignment operator does not append. It simply replaces the contents with the new text. The assignment operator can also be applied to a ComboBox for writing to its field area without adding the string to its list of values. Operator ~

6 The clear operator simply clears the contents of a field or text area. For instance ~MyCanvas::Text blanks the field Text. When the clear operator is applied to a ComboBox, it removes all items in the list component of the ComboBox. Operator + The add operator appends new strings to the list of vlaues of a ComboBox. The following statement shows its syntax. This is useful for setting initial values for a ComboBox. MyCanvas::Values + Hello World ; Operator - The remove operator is the opposite of add operator and uses the same syntax. Operator [] The bracket operator conveniently allows access to individual items in the list component of a ComboBox, as shown by the following statements. string newvalue = Hello World ; MyCanvas::Values[n] = newvalue; string itemvalue = MyCanvas::Values[n]; Now the string itemvalue has the value Hello World. Operator size The size operator returns the number of items in the list component of a ComboBox. Here is how it may be used. int number = size(mycanvas::values); Operator $ The visibility (toggle) operator shows or hides entities. For instance, $MyCanvas::Done will hide the button Done if it is showing, and show it otherwise. Operator? The visibility state operator evaluates to a boolean. It returns True if the entity is showing, otherwise it returns False. An example of its use is?mycanvas::done. Operator!

7 The active (toggle) operator makes entities show as active or inactive (enabled/disabled). Its syntax is the same as visibility operator. Operator ^ The active state operator evaluates to a boolean, reporting on whether an entity is currently active (enabled/disabled). Its syntax is same as visibility state operator. The focus operator sets the focus to an entity in a canvas. For instance, the following statement sets the focus to the text area identified by Text in our example Operator & This operator reports whether an entity has the focus, or is highlighted. It returns a boolean, with usual syntax for similar operators: &MyCanvas::Text; Message Boxes A message box may be used for providing information, requesting confirmation by user, or reporting an error condition. Furthermore, depending on situation, a message box may provide a single button OK, two buttons Yes and NO, or three buttons, which adds a Cancel button. Finally, a message box should show some text. In Z++ the number of buttons is indicated by the following styles. _MBT_Single_Button _MBT_Double_Button _MBT_Triple_Button The intent, such as information or confirmation is indicated with an operator preceding the style. The question mark is for confirmation, the colon is for information, and the exclamation mark indicates an error. These operators decorate the message box according to the intent. A message box is written to a canvas and returns an integer value of 0, 1 or 2 for the button selected by the user. For instance, using MyCanvas as an example, here are some illustrations. response = MyCanvas << "Do you wish to continue?"? _MBT_Triple_Button; This message box has confirmation style with three buttons. It returns the selected button to the integer object response.

8 MyCanvas << "Error Reading file."! _MBT_Single_Button; This message box has a single button and indicates an error condition. On the other hand, the following message box is decorated for information. MyCanvas << "Transmission Complete." : _MBT_Single_Button; The compiler checks for correct combination of style and number of buttons. For instance, logically speaking, an information box can only show an "OK" button. So the compiler will complain about the use of double or triple buttons for an information box.

9 GUI Maker Tool The GUI Maker can be launched by right-clicking Resource Files in project tree, or by double clicking a resource file in a project. In the latter case the tool will also sense the platform. Otherwise the platform can be set from the tool itself. In title area we see the platform (Window). If a resource file were loaded, its name would follow the platform tag. The area below the toolbar is the drawing canvas area. The drawing canvas area represents a Z++ canvas. The drawing area can be resized for desktop. For PDA the size is the entire PDA screen. Further more, the location of drawing canvas as seen will appear on a desktop screen at execution time. Thus, you may create several canvases, with different sizes and appearing at different locations. The following sections illustrate menu items. Toolbar buttons present faster way of accessing some of the menu items, and their tips properly identify them.

10 Resource Menu Item Menu selections Open and Exit are straightforward. The selection Start new resource clears the drawing canvas (reminding you to save any work). The terms Save and Generate mean the same thing. Resources are considered saved when they have been generated. A generated resource can be opened (loaded) for further editing. The Save as selection means the same thing as regenerating under a different name. If you wish to regenerate an already saved resource, simply right-click anywhere on the drawing canvas and select accept without changing anything. This action simply marks the resource as unsaved. Canvas Menu Item The combobox in toolbar allows switching to various canvases in a resource. The name of a canvas must be a Z++ identifier and is set via the selection Change canvas name. The new name will be reflected in the toolbar combobox.

11 A resource can contain many canvases. The Add selection allows adding a canvas to resources, and the Remove selection does the opposite. Palette Menu Item Palette lists the currently supported controls. A Text area is a multi-line field. The controls are identical for desktop and PDA. However, RadioButtons appear as CheckBoxes on Palm. Nevertheless the behavior of controls is uniform and platform independent. Platform Menu Item GUIs are platform-independent within categories. For instance, desktop is a category. Therefore, GUI made for Windows will work the same way for UNIX. However, you may choose to have more resources for one of the platforms. The GUI maker shows the platform of your selection in its title bar, for your convenience.

12 Palette Selections The Palette menu item shows the available controls. Clicking the left mouse button on an item, such as Field, changes the cursor to a hand. You do not need to hold the mouse button down. Simply move the hand to some point in the drawing canvas area, and leftclick again to drop your selection onto the canvas. Once you have dropped a control onto the canvas, you can resize, move and edit properties of the control. Moving a control Left click on a control changes its color to red indicating that you can move and resize the control. Now you can left-click and hold on the red control. The cursor shape shows the action depending on where you clicked the mouse button. For instance a cross-shape is for moving, etc. If a control can be resized, clicking near sides or corners will change the shape of the cursor signaling the possibility of action. The sizes of some controls are determined automatically. For instance, a label adjusts its size to its text. Some controls can only be resized in certain directions. For instance, a field can only be resized horizontally. A field is a single line and cannot be resized vertically. On the other hand, a text area, button or group box can be resized in all directions. Remark. When a control is showing in red, you can move it by single pixels using the arrow keys (cursor moving keys). Holding shift key down allows moving the control object along its diagonals. Remark. When a control is showing in red, clicking anywhere outside of the control turns it back to the black color. Editing a GroupBox A group box surrounds a set of controls providing a visual grouping. In the course of editing a canvas, more frequently we need to move the controls within a group box rather than the group box itself. Therefore, a left-click on a control in a group box will turn the control red, instead of the group box. In order to edit the group box itself, hold the shift-key down and left-click any where in the group box. This will turn the group box red, ready for editing. The mouse right-click is less frequently used (manual editing). In the case of a group box, find a spot that is not on any control in the group box, and do a right click.

13 Manual Editing A right-click on a control pops up a dialog for editing its properties manually. Below is an example of a popup for ComboBox control. The following is the popup for a Button. Two fields require explanation. First, all controls will have the field Identifier. This is the name that appears in the header file generated by GUI Maker. It must be a Z++ identifier. Initially it appears as five asterisks. Second, some controls like button accept a string as their label. This can be the same as the identifier or any printable string. Initially it is set to Blank for all controls.

14 Z++ canvas identifier The identifier for the canvas as a Z++ object is just the name of the canvas as shown in the toolbar combobox. Initially it is set to _UnNamed_Canvas, which is not a Z++ identifier. Note that Z++ identifiers do not start with underscore. On the other hand, enumeration literals must start with the underscore symbol. Files created by GUI Maker Below is a canvas for Windows Mobile. This resource has been saved because we see a filename in the title area, namely Compute. When generating a resource that has not been saved, GUI Maker pops up the following screen. Note the extension ZRC for a Z++ resource file. The initial name Unnamed is a reminder that the file has not been named.

15 The GUI Maker creates two files with the same name. For our example these are Compute.zrc and Compute.h. The header file contains the Z++ canvas structure for inclusion in source files. The resource file ZRC can be added to the resource folder of the project for future editing.

16 Folder Arrangement for Resources Remark. Resource conversion is only necessary among different platforms. For instance, for Windows Mobile you can simply use WinMobile_320x240 for all resolutions. Specifically, no conversion is needed between Windows and Linux desktops. However, if you wish to have different versions for certain resolutions of Windows, keep in mind that all converted resources must have the exact same entities (controls) and there will only be one generated header file. The positions and sizes of entities can be different, however. You can hide or show different sets of entities for different versions, using the same Z++ source files for the project, and the preprocessor define mechanism. Although Z++ automates the entire process of conversion, some idea of folder arrangements will be useful. The arrangement is simple and straightforward. When you create your first resource, a folder named Resource is added to the project. As you know, when you create a project the IDE creates three folders, Release, Debug and Temp under project s folder. The Resource folder is created at same level as other folders, under project s folder. When GUI Maker generates code for the Linker, it also generates an include file with regard to the resources. This include file is stored in the Resource folder. You will need to include this file in your source files, and may also want to add it to the project tree under Header Files so you can open it via a double-click. For each platform, the GUI Maker creates a folder under the Resource folder mentioned above. For instance, the name of this folder for Windows Mobile, device 320x240 will be WinMobile_320x240. The information in these folders is used during switching platforms. Furthermore, in order to switch platforms you need to add your resource ZRC files to the project tree under Resource Files. You only need to do that for a single platform, the one you develop first. Once your project is complete, use the GUI Maker to convert it to all desired target platforms. The GUI Maker will make new folders for each platform you convert to. These folders are used internally and automatically when you switch to a converted platform. You simply leave them alone so the tools do not lose track of the state of your project. Remark. Conversion is done via GUI Maker from Platform menu. You should convert all resources by loading them into GUI Maker, and selecting the target platform. On the other hand, switching to another platform is done via IDE. Right-click on resource folder of the project, and a popup menu will allow you to switch to a converted platform.

17 Tab Order For Windows Mobile Z47 indicates highlighting with boldface-underlined characters. The tab order is maintained by the Z47 processor, and specified in the GUI Maker. Since users prefer to use the scroll (arrow) keys on PDA, you can map the arrow keys to the tab key as follows. case _IES_Left_Arrow_Signal: Canvas_Name <- _IES_Tab_Key_Signal; case _IES_Right_Arrow_Signal: Canvas_Name <- _IES_Tab_Key_Signal; Now, when a user presses the left-right scroll keys Z47 will receive a signal as if the tab key was pressed.

18 Actual size of text on target device Clicking on controls label, checkbox or radio-button shows the space their text will take on the target device. In the above example, text is in bold and will draw inside the red rectangle on the destination device (in this case Windows Mobile).

19 Menu Resource In order to add a menu resource select Add menubar to canvas from Canvas drop down menu, as shown below. This will add an empty bar to the top of your canvas. Menu commands, submenus and separators are easily added to the menubar, as we will illustrate shortly. First, we must add a menu item to the menubar. Initially, the bar has no menu items on it, so you can right click anywhere on the bar. Doing so pops up the following window.

20 Menubar identifier is for referring to the menubar in your program. Modify the default identifier to your choice. For purposes of this illustration we will use FirstMenu. Next enter an identifier for your menu item, and a value that will show on the menubar. The two could be the same string. In the example shown below, we have made two menu items, Computations and Actions. Note that, if you right click on the menubar, but not on any menu item, you will see the preceding window, which allows you to add new items, like Computations.

21 Now, we illustrate how to create commands and recursive submenus for menu items on the menubar. Let us add a few items to the menu item Operations. Right-click on Operations, and you will see the following, except that we have added a few items, which we will discuss momentarily. We have added a command, a separator and a submenu.

22 The title tells you that you are adding item to menu item Operations. Let us look at first item added [cmd] Module == Remote Module. The GuiMaker appends the tag [cmd] so you know this is a menu command. As you see with regard to Database entry, the tag is [menu], meaning that Database is a submenu. Let us begin from start and add the command Module. Below is how it will look. Note that the button Add is now enabled. Also, since we intend to use Module as a command, we are not going to check the box This is Submenu. The Entry Value is what will show in the menu. The Command/Submenu must be a Z++ identifier so you can refer to it in your program.

23 Click Add and you will see the following. That means your entry has been added. Now click the entry you just added, and you will see the following.

24 If you need to modify the entry, click Edit Entry, and you will see the following. In preceding figure you also see Remove and Separator enabled. If you click Separator, a menu separator will be inserted after the highlighted item, in this case, Module. If you wish to insert a new item in the middle of the list, first enter the item s name and value, then highlight an item in the list. The Insert button will become enabled, allowing you to insert the new item after the highlighted item. Clicking Add will always append the new item to the bottom of the list. Suppose we add a Database submenu entry after the separator. So, how do we add commands and submenus to Database entry? Click the entry to highlight it. You will see the following in which the button Extend Submenu is enabled.

25 Since menus are recursive, clicking Extend Submenu will pop up an identical dialog. Below we show that with a few items entered in the Database Submenu.

26 The submenu recursion can be as deep as you like. Once done, continue to click Accept until you are back to the GuiMaker tool. Note. Sometimes when you click Accept or other buttons, the next level dialog may remain behind IDE window. Nothing is lost. The window needs to be brought to front.

27 Generated Header File (Menu) There is so little, which a developer needs to know, that one example will cover it all. Below is the include file that the GUI Maker generated for one of the examples packaged with Z++ Visual. // Generated by Z++ GUI Maker menu Computations command Cast; command Array; end; menu Database command Connect; command Query; command Fetch; command Disconnect; end; menu Operations command Module; menu Database; end; menu Actions command Erase; command Exit; end; menubar FirstMenu menu Computations; menu Operations; menu Actions; end; canvas Compute menubar FirstMenu; TextArea Result; end; Figure 1. Listing of a generated (resource) include file. Read the file from bottom up. First there must be a canvas. In this example, the canvas is named Compute, and has two items: a menubar and a TextArea. The menubar FirstMenu is defined above the canvas. This menubar has three menu items showing on it: (from left-to-right on the bar) Computations, Operations and Actions. Members of a menubar can only be menus. Recursion begins with (drop-down) menus, which can include commands and other menus.

28 The structure of the file is now clear. For every menu item appearing as a member of the menubar or another menu, there must be a definition preceding it (above it). Commands are terminal (do not require a definition). Programming Menu Commands This is trivial. All menu commands, regardless of nesting level, are treated as canvas entities. That means they appear directly as cases of select statements. For an example, look at menu Actions. This menu has two commands, Exit and Erase. Below is the code using them, just like members of the canvas, like Result. select(e.entity) case Result: // Text Area for showing results case Exit: // Exit application Compute <- _IES_Erase_Signal; case Erase: // Clear text area ~Compute::Result; // Other cases endselect; As illustrated above, menu commands can be referenced directly as labels for the cases of select statements. However, if you wish to enable or disable a submenu or a command, you will need to look at the generated include file, in Figure 1. For instance, suppose we want to hide the three commands of Query, Fetch and Disconnect of the Database menu, until user connects to a database server. The hide/show operator is!. case _IES_Draw_Signal:!Compute::FirstMenu::Operations::Database::Query;!Compute::FirstMenu::Operations::Database::Fetch;!Compute::FirstMenu::Operations::Database::Disconnect; As usual, and following the same rules, you start with the canvas Compute and resolve your path all the way to the entity that you wish to operate upon. Operators for Menu Items Only a few operators are usable with menu item (command/submenu). Basically, we need to enable/disable a menu item and check on its state as enabled or disabled. Another operation of interest is highlighting a menu item, usually by putting a small checkmark to the left of the item. We illustrate the use of these operators in this section. Operator!. This operator toggles the active state of a menu item (submenu or command). If the item is active, it will make it inactive and vice versa.

29 Operator ^. This operator returns a boolean reporting the state of a menu item. It returns True when the item is active, and False otherwise. Operator <<. This operator takes a Boolean for its operand. If True is sent to a menu item, it will be highlighted (a checkmark will show). Otherwise, the highlighting will be removed. Below is an example of its syntax. The command Next belongs to submenu Options of menubar FirstBar, in canvas DemoMenu. DemoMenu::FirstBar::Options::Next << True; To get the highlighting state of a menu command, use operator >>, which returns a Boolean with standard semantics.