WINGs_tutorial/WINGstep3.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
   2 <!-- saved from url=(0074)WINGStep3.html -->
   3 <html lang="en"><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>3 Steps to Make a WINGs User Interface</title>
   4 <meta http-equiv="Content-Type" content="text/html">
   5 <meta name="keywords" content="WINGs, tutorial, GUI, Window Maker, widget, Linux">
   6 <meta name="description" content="WINGs library tutorial">
   7 <meta name="license" content="GNU Free Documentation License">
   8 </head>
   9
  10 <body>
  11 <table align="JUSTIFY" width="100%"><tbody><tr><td align="LEFT"><a href="WINGStep2.html">LAST: Step 2 Processing Events</a></td><td align="CENTER"><a href="WINGtoc.html">Contents</a></td><td align="RIGHT"><a href="WINGsRemark.html">NEXT: Programming Details</a></td></tr></tbody></table>
  12
  13 <h4>Step 3: Adding widgets to a window</h4>
  14
  15 <h5>Adding buttons to a widget</h5>
  16 <p>As a window is a widget, we can create a button for it with the function<br>
  17 <code> WMButton * WMCreateButton (WMWidget *parent, WMButtonType type)</code><br>
  18 To make the button visible, the function <code>WMMapSubwidgets</code> may be called on the window. A call to WMMapWidget on the button will do the same of course.  Before mapping the button, its properties can be set with functions whose names speak for themselves
  19
  20 </p><p>
  21 </p><ul><li><code> void WMSetButtonText (WMButton *bPtr, char *text)</code>
  22 </li><li><code>void WMSetButtonTextAlignment (WMButton *bPtr,WMAlignment alignment)</code>
  23 </li><li><code> void WMSetButtonAction (WMButton *bPtr, WMAction *action, void *clientData)</code>
  24 </li><li><code> void WMMoveWidget (WMWidget *wdiget, int pixelstoright, int pixelsdown)</code>
  25 </li><li><code> WMScreen * WMWidgetScreen (WMWidget *widget)</code>
  26 </li><li><code>  WMSize WMGetViewSize (WMView *view)</code>
  27 </li><li><code>void WMMapSubwidgets (WMWidget *widget)</code>
  28 </li></ul>
  29
  30 <p>As windows and buttons are both widgets, <code>WMResizeWidget()</code> is the same as for the window <a href="WINGStep1.html#WindowProps">above</a>, just as the function to set the background colour. Sizing and moving is in pixels, movements are in pixels from the parent widget's upper left corner. The default action on a button, which is a mouse click, will call the WMAction function, just as happens with the <a href="WINGStep2.html#WindowCloseAction">CloseAction</a> on the window. WMAlignment can be WALeft, WACenter, WARight or WAJustified.
  31
  32 </p><p>The different WMButtonTypes are <img src="./WINGstep3_files/Buttons.jpeg" align="right">
  33 </p><dl><dt>Touch buttons:</dt><dd><code>WBTMomentaryPush, WBTMomentaryChange,WBTMomentaryLight </code>
  34 </dd><dt>Alternate on/off buttons: </dt><dd><code>WBTPushOnPushOff, WBTOnOff, WBToggle</code>
  35 </dd><dt>Checkbox with label next to it:</dt><dd> <code>WBTSwitch, WBTRadio</code>
  36 </dd></dl>
  37 Particular behaviour of a button can be obtained by using the function<br>
  38 <code>WMButton * WMCreateCustomButton (WMWidget *parent, int behaviourMask)</code><br>
  39 By default a new widget will be placed in the window's top left corner. <code>WMMoveWidget</code> is used to place it correctly.
  40 <p>Buttons can be grouped together by using a WMBox widget. You would do this when you want to do something fancy with the buttons, eg. filling the width of a part of the window, and resizing with that part. Create the box before creating the button, WMMap the button, and next add the latter's view, extracted with WMWidgetView() to the box:
  41 </p><ul>
  42 <li><code>WMBox * WMCreateBox (WMWidget *parent)</code>
  43 </li><li><code> void WMSetBoxHorizontal (WMBox *box, Bool TrueorFalse)</code>
  44 </li><li><code> void WMAddBoxSubview (WMBox *box, WMView *buttonsview,
  45                              Bool expand, Bool fill, int minSize,
  46                              int maxSizeor0, int space)</code>
  47  </li><li><code>void WMSetBoxBorderWidth (WMBox *box, unsigned width)</code>
  48 </li><li><code>void WMSetViewExpandsToParent (WMView *boxview, int leftOffset,
  49                                       int topOffset, int rightOffset,
  50                                       int bottomOffset)</code>
  51 </li></ul>
  52 <p>In the <code>WMAddBoxSubview</code> function, setting expand to True will stretch the button to the height of the box. <code>space</code> sets the space after the button. To resize the widgetbox with the window, you can use the <code>WMSetViewExpandsToParent</code> function. Otherwise, you can calculate your own positions, and move the box to where it is supposed to be in a resized window. There are other ways to group buttons, or other widgets, eg. by a <a href="WINGStep3.html#talkFrame">frame</a>.
  53
  54 </p><h6>Resize events</h6>
  55 To know the current window's size, and the size of any other widget, there is the function <code>  WMSize WMGetViewSize (WMView *view)</code>. As before, the function <code>WMWidgetView</code> casts the widget into a view. <code>WMWidgetScreen</code> returns a pointer to the screen in which the widget was created.
  56
  57 <p>We thus can get the window's size, and place widgets in their correct positions. What is left to do is a function which handles the event that the user resizes the window. The buttons, or the box containing them, should move to their correct positions in the window again in such an event, or resize with the window itself. There is an event <code>WMViewSizeDidChangeNotification</code> when the window is resized. For a WMWindow win, passing WMWidgetView(win) as the last argument to the function below will define what to do when this event occurs.
  58 <br><code> void WMAddNotificationObserver (WMNotificationObserverAction *observerAction, void *observer,const char *name, void *object)</code><br>
  59 The third argument should be the event's name (WMViewSizeDidChangeNotification), and the first argument is the name of the function which will be called. This function should look like <code>void observerAct(void *self, WMNotification *notification)</code>. It is all done in the sample code <a href="FourthWindow.c">here</a>.
  60
  61 </p><h6>Adding the event handlers and widgets to the application</h6>
  62 In the FirstWindow code, we insert the following lines to handle the resize notification:<br>
  63 <pre><code>   WMSetViewNotifySizeChanges(WMWidgetView(win), True);
  64   WMAddNotificationObserver(resizeHandler, NULL, WMViewSizeDidChangeNotification, WMWidgetView(win));</code></pre>
  65 <p>Before the <code>main</code> function we define the function (<code>resizeHandler</code>) which will handle the resize event for the two widgets, the text area and the box with buttons. There is a global variable ButtonsetSize, which contains the size of the box with buttons:
  66 </p><pre><code> WMSize ButtonsetSize;
  67  static void resizeHandler(void *self, WMNotification *notif){
  68  WMSize size = WMGetViewSize(WMWidgetView(win));
  69  WMMoveWidget(box, size.width-ButtonsetSize.width, size.height-ButtonsetSize.height);
  70  WMResizeWidget(text, size.width-MARGIN -10, size.height-80);
  71 }
  72 static void handleEvents(XEvent *event, void *data)
  73 {int i=0;
  74     WMWidget *widget = (WMWidget*)data;
  75     switch (event-&gt;type) {
  76     case ButtonPress:
  77       while (i&lt;40)textbuf[i++]=' ';
  78       snprintf(textbuf,39,"Button down at (%i,%i) \n-",event-&gt;xbutton.x,event-&gt;xbutton.y);
  79       WMFreezeText(text);
  80       WMAppendTextStream(text,textbuf);
  81       WMThawText(text);
  82       break;
  83     }
  84 }
  85
  86 </code></pre>
  87 The buttons keep their size, but are moved to stay in the bottom right corner, the text area is resized along with the window, but stays 80 pixels away from the window bottom border. We also do something useful with the mouseclicks on the window itself. This is done in the function handleEvents. The event ButtonPress has the click time and position in a member <code>.xbutton</code>. When the button is pressed, we get that information, and print it to the text area.
  88
  89 <p> The text is written to a <a href="WINGLib.html#TextArea">text area</a>. Function names for it are self-explanatory. We create this widget after creating the window. It will be WMmapped by the final <code>WMMapSubwidgets</code>. The code for setting it up is just:
  90 </p><pre><code> text = WMCreateText(win);
  91   WMResizeWidget(text, WINWIDTH-MARGIN, WINHEIGHT -80);
  92   WMMoveWidget(text, 10, 10)</code></pre>The text is written to the area by passing character strings to the <code>WMAppendTextStream</code> function.
  93
  94 <p>The important functions in creating the box and its widgets are:
  95 </p><pre><code> box=WMCreateBox(win);
  96  WMSetBoxBorderWidth(box, MARGIN);
  97  WMSetBoxHorizontal(box, True);
  98  Button =WMCreateButton(box,WBTMomentaryPush);
  99  WMSetButtonAction (Button, selectFiles, NULL);
 100  WMMapWidget(Button);
 101  ButtonsetSize = WMGetViewSize(WMWidgetView(QuitButton));
 102  WMAddBoxSubview(box, WMWidgetView(QuitButton), True,False, 60, 1000, MARGIN);
 103   /*-- make and add another button --*/
 104  WMResizeWidget(box, 4*MARGIN+2*ButtonsetSize.width,2*MARGIN+ButtonsetSize.height);
 105  ButtonsetSize =WMGetViewSize(WMWidgetView(box));
 106  resizeHandler(NULL,NULL)</code></pre>
 107 <img src="./WINGstep3_files/FirstWindow4.jpeg" align="LEFT" alt="Application window" hspace="#5">The box is created before the button is, because the button will have to be created with the box (its parent widget) as its first argument. The box is the "outer" widget and will be mapped with  <code>WMMapSubwidgets</code>, but we map the buttons separately. The function which will be called on the default button event is closeAll() for the quit button. The file button will call the <code>selectFiles()</code> function, in which we open a <a href="WINGLib.html#FileSelect">file selector</a> widget.  We have left it to WINGs to decide what size the button will be. We temporarily use ButtonsetSize to store this size. We add the button's view to the box. After adding all the buttons, We store the size of the resulting box, and use it in our <kbd>resizeHandler</kbd> function to keep the box in the corner. <img src="./WINGstep3_files/OpenFileDialog.jpeg" align="Right" width="20%" alt="File selector widget" hspace="#5">.Following the <a href="FourthWindow.c">source code</a>, pressing the file button will pop up the file selector dialog, and the name of the selected file is printed in the text area. Notice that, without the box widget, we would need two global Button pointers to change the position of both buttons in the <kbd>resizeHandler</kbd> function. We now need one Button pointer, which can remain local to <code>main</code>.
 108
 109 <p><a href="FourthWindow.c">Here</a> is the full code which we have now. As we have a text area, we can print text to it, as long as we are sure that the widget has not been destroyed. The scroll bar next to the area is obtained with one single <a href="WINGLib.html#TextArea">function</a> call.
 110
 111 </p><h6>Frames</h6>
 112 <p>The WMBox needs quite some configuration. It is not really intended for putting two simple buttons in a corner. We can use a <a name="talkFrame"></a><a href="WINGLib.html#Frames">frame</a> to keep widgets together and move them with one single pointer. For buttons, we could also use the <code>WMGroupButtons</code> function to handle a group of buttons with just one pointer. To use a frame, use this code, instead of the WMBox functions: At global scope:
 113 </p><pre><code>WMFrame *controlframe;
 114 static void resizeHandler(void *self, WMNotification *notif){
 115      WMSize size = WMGetViewSize(WMWidgetView(win));
 116      WMMoveWidget(controlframe, size.width-ButtonsetSize.width, size.height-ButtonsetSize.height);
 117      WMResizeWidget(text, size.width-MARGIN -10, size.height-80);
 118 }</code></pre>
 119 In <code>main</code>:
 120 <pre><code>  controlframe=WMCreateFrame(win);
 121   Button =WMCreateButton(controlframe,WBTMomentaryPush);
 122   ButtonsetSize = WMGetViewSize(WMWidgetView(Button));
 123   WMMoveWidget(Button,MARGIN, MARGIN);
 124   /* (code to create a second button of the same size, with the same pointer)  */
 125   WMMoveWidget(Button,2*MARGIN+ButtonsetSize.width, MARGIN);
 126   ButtonsetSize.width = 3*MARGIN+2*ButtonsetSize.width;
 127   ButtonsetSize.height=2*MARGIN+ButtonsetSize.height;
 128   WMResizeWidget(controlframe,ButtonsetSize.width,ButtonsetSize.height);
 129   WMMapSubwidgets(controlframe);</code></pre>
 130
 131 <p>As we created the buttons inside the frame, we WMMoveWidget them along coordinates with respect to the frame's upper left corner. We have left it to WINGs to set the buttons' size, so we get their size with <code>WMGetViewSize</code>. With the button sizes, we calculate what size the frame is to have, and how far we need to move the buttons from the upper left corner to get them to the right place. We WMMap both buttons inside the frame with <code>WMMapSubwidgets(controlframe);</code>. The frame is the outer widget, and will be WMMapped just before the window. Replacing the box with the frame, we get <a href="FifthWindow.c">this</a> source code. After compiling, we get the same application. The obvious frame properties are set with the <a href="WINGLib.html#Frames">frame functions</a>
 132
 133 </p><h5>Next sections</h5>
 134 <p> The three steps up till now have shown the important points in programming with the WINGs library. The basics are all the same all the time. Create, specify WMAction, define the WMAction function somewhere, WMMap the widget. If this won't do, use <a href="WINGLib.html#Notification">PostNotification</a>, and <code>AddNotificationObserver</code> to the widget which should react to it.
 135 </p><p>From the next sections, the <a href="WINGLib.html">library description</a> gives a whole range of widgets which you can fit into the window this way, and related functions and data structures. There is sample code for those widgets whose code seems a bit more involved. The only thing which cannot be obtained by a simple function call is a menu with submenus, which is to work under any window manager, not just Window Maker. The <a href="WINGMenu.html">third programming detail section</a> explains, how to programme this kind of menu. The other two programming detail sections are not about the WINGs/wraster/windowmaker libraries themselves, except for a <a href="WINGsRemark.html#talkIcons">short section</a> on the use of the WINGs functions to insert icons into widgets. Detail <a href="WINGsRemark.html">section 1</a> contains an  <a href="WINGsRemark.html#talkMessageLog">example</a> of how to get rid of the disappointing xterm window which you need to start your windowed application from, to read its messages on stderr or stdout. It shows the standard code to open a <a href="WINGsRemark.html#talkMessageLog">logging window</a> on the screen when needed. For convenience, it uses xconsole for this, a standard application on unix systems with X11. The same section 1 shows how to get the correct information about <a href="WINGsRemark.html#talkResolution">monitor resolution</a> when a virtual screen is used. Detail <a href="WINGGraphics.html">section 2</a> gives code samples which demonstrate how to mix Xlib code with the WINGs library. Xlib is the library which gives direct access to the X-server, and which is the underlying code to the WINGs library itself. It also contains a <a href="WINGGraphics.html#talkOpenGL"> section</a> which shows how to use OpenGL 3D graphics code in a WINGs frame. These extra sections do not explain all the details on the used libraries. However, by just following the code examples, you can reproduce their results, and change them to use them in your own programmes.
 136
 137
 138 <br>
 139 </p><p>
 140 </p><table align="JUSTIFY" width="100%"><tbody><tr><td align="LEFT"><a href="WINGStep2.html">LAST: Step 2 Processing Events</a></td><td align="CENTER"><a href="WINGtoc.html">Contents</a></td><td align="RIGHT"><a href="WINGsRemark.html">NEXT: Programming Details</a></td></tr></tbody></table>
 141
 142
 143 </body><style type="text/css">embed[type*="application/x-shockwave-flash"],embed[src*=".swf"],object[type*="application/x-shockwave-flash"],object[codetype*="application/x-shockwave-flash"],object[src*=".swf"],object[codebase*="swflash.cab"],object[classid*="D27CDB6E-AE6D-11cf-96B8-444553540000"],object[classid*="d27cdb6e-ae6d-11cf-96b8-444553540000"],object[classid*="D27CDB6E-AE6D-11cf-96B8-444553540000"]{      display: none !important;}</style></html>