aboutsummaryrefslogtreecommitdiffstats
path: root/doc/MBWM2-Overview.xml
blob: afcab2e06815f4aa54974bd1a3551786395841a5 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<article id="mbwm2-overview" lang="en">
  <articleinfo>

    <title>Matchbox Window Manager II</title>
	<subtitle>Overview</subtitle>

    <author>
      <firstname>Tomas</firstname> <surname>Frydrych</surname>
      <affiliation>
        <orgname>OpenedHand Ltd</orgname>
      </affiliation>
      <email>tf@o-hand.com</email>
    </author>

    <revhistory>
      <revision>
         <revnumber>0.1</revnumber>
         <date>22 November 2007</date>
         <revremark>Initial draft</revremark>
      </revision>
    </revhistory>
  </articleinfo>

  <?hard-pagebreak?>

  <section id="intro">
    <title>Introduction</title>

    <para>Matchbox Window Manager II is a component framework for building
    customised window managers providing PDA-like (i.e., restricted-stack),
    window management compliant with the <ulink
    url='http://tronche.com/gui/x/icccm/'>ICCCM</ulink> and <ulink
    url='http://standards.freedesktop.org/wm-spec/wm-spec-1.4.html'>NET
    WM</ulink> specifications.
    </para>

    <para>Matchbox Window Manager II (MBWM2) builds on the success of the
    original Matchbox Window Manager, using the same window-management paradigm,
    but offering significantly greater flexibility making it easy to create
    custom managers matching requirements for specific HW and UI design.
    </para>

    <para>The framework is built on the top of a lightweight object system, and
    provides a set of ready-made building blocks encapsulating the key parts and
    functionality of a window manager. The object system makes it easy to
    subclass the provided objects in order to achieve the required behaviour.
    </para>


    <para>The key features of the MBWM2 framework are:
    </para>

    <itemizedlist>
      <listitem>
	<para>Ready-made client types for standard window types as defined by
	the <ulink url='http://tronche.com/gui/x/icccm/'>ICCCM</ulink> and
	<ulink
	url='http://standards.freedesktop.org/wm-spec/wm-spec-1.4.html'>NET
	WM</ulink> specifications.
        </para>
      </listitem>

      <listitem>
	<para>Theme engines allowing powerful and yet minimal-effort theming.
        </para>
      </listitem>

      <listitem>
	<para>Window-compositing capabilities (optional).
        </para>
      </listitem>

      <listitem>
	<para>Support for GLib main loop (optional).
        </para>
      </listitem>

    </itemizedlist>

  </section>

  <?hard-pagebreak?>

  <section id="key-blocks">
    <title>Key Building Blocks</title>

    <para>This section of the document describes the key blocks that are used to
    build a MBWM2 manager.
    </para>

    <section id="MBWindowManagerClient">
      <title>MBWindowManagerClient</title>

      <para>Each window managed by MBWM2 is encapsulated by a client
      object. MBWindowManagerClient is the base, abstract, type which provides
      API for manipulating the client objects, decorating the wrapped window as
      required.
      </para>

      <para>The base MBWindowManagerClient type is then sub-classed to handle specific
      window types according to requirments. To this end, the
      MBWindowManagerClass exposes a number of virtual methods that the
      sub-classes can override.
      </para>

      <section id="client-virtual-methods">
	<title>MBWindowManagerClient virtual methods</title>

	<itemizedlist>

	  <listitem>
	    <para>realize: responsible for creation of client resources, such as
	    frame windows, and reparenting client windows. This method is
	    usually overwritten by clients that do not require a frame.
            </para>
	  </listitem>

	  <listitem>
	    <para>geometry: distributes the overall geometry available to the
	    client between its constituent parts (the client, frame, etc).
            </para>
	  </listitem>

	  <listitem>
	    <para>stack: carries out any action necessary to stack the client
	    correctly, e.g., for clients with transient children, it ensures
	    that both the client and the children are stacked correctly.
            </para>
	  </listitem>

	  <listitem>
	    <para>show: carries out any required custom actions when the client is
	    changing from a hidden to visible state; most clients need not to
	    implement this method.
            </para>
	  </listitem>

	  <listitem>
	    <para>hide: carries out any required custom actions when the client
	    is changing from a visible to hidden state; most clients need not to
	    implement this method.
            </para>
	  </listitem>

	  <listitem>
	    <para>sync: flushes any internally scheduled changes to the display.
            </para>
	  </listitem>

	  <listitem>
	    <para>focus: carries out any custom action required when the client
	    is given focus; most clients need not to implement this method.
            </para>
	  </listitem>

	  <listitem>
	    <para>theme_change: carries out any actions required when the theme
	    has changed (for example, recreating decor windows, etc.).
            </para>
	  </listitem>

	  <listitem>
	    <para>detransitize: this method is responsible for terminating
	    any relationship between the (transient) client and its parent; it
	    is typically called early in the process of the WM releasing a given
	    client. Most clients do not need to implement this method.
            </para>
	  </listitem>

	  <listitem>
	    <para>stacking_layer: calculates the stacking layer for the client. This
	    method only needs to be implemented by clients whose stacking
	    requirement change dynamically; for most clients the stacking layer
	    is static, in which case it is enough to initialise it from the
	    object _init method.
            </para>
	  </listitem>

	</itemizedlist>

      </section>

    </section>

    <section id="client-subclasses">
      <title>Specialized Client Types</title>

      <section id="fundamental-client-types">
	<title>Fundamental Client Types</title>

	<para>The MBWM2 framework recognises eight fundamental client types, for
	each of which it provides a sub-class of MBWMWindowManagerClient, listed
	in the following section; these sub-classes can be further sub-classed
	or replaced, should the customisation of the WM require that.
        </para>

	<para>The type of a given client can be queried using the
	MB_WM_CLIENT_CLIENT_TYPE() macro; the client type values are
	or-able. (NB: the client type should not be confused with the type of
	the object handling the client; the object type id is unique for each
	object class, and it is not or-able.)
        </para>
      </section>

      <section id="standard-client-subclasses">
	<title>Standard Client Subclasses</title>

	<para>The standard sub-classes of MBWindowManagerClient are in fact not
        derrived directly from MBWindowManagerClient, but from an intermediary
        helper class MBWMClientBase; they are as follows:
        </para>

	<itemizedlist>
	  <listitem>
	    <para>MBWMClientApp, encapsulating top-level application windows.
            </para>
	  </listitem>

	  <listitem>
	    <para>MBWMClientDialog, encapsulating dialogues.
            </para>
	  </listitem>

	  <listitem>
	    <para>MBWMClientPanel, encapsulating panels, such as task-switchers.
            </para>
	  </listitem>

	  <listitem>
	    <para>MBWMClientDesktop, encapsulating a desktop application.
            </para>
	  </listitem>

	  <listitem>
	    <para>MBWMClientInput, encapsulating input windows, such as virtual
	    keyboards.
            </para>
	  </listitem>

	  <listitem>
	    <para>MBWMClientMenu, encapsulating menus.
            </para>
	  </listitem>

	  <listitem>
	    <para>MBWMClientNote, encapsulating non-interactive message windows.
            </para>
	  </listitem>

	  <listitem>
	    <para>MBWMClientOverride, encapsulating windows with override-redirect
	    attribute set (this type is only used when running in compositing
	    mode, since override windows are, by definition, unmanaged).
            </para>
	  </listitem>

	</itemizedlist>

      <para>Each individual client-type provides specific behaviour, primarily
      in regards to resizing and stacking. For an example of how to replace a
      default clients implementaion with a custom one, see the maemo WM in
      src/managers/maemo.
      </para>

      </section>

    </section>

    <section id="MBWMTheme">
      <title>MBWMTheme</title>

      <para>The MBWMTheme is an abstract object encapsulating a theme
      engine. It handles parsing of the XML theme description, API for querying
      various parameters that are specified by a theme, and API for drawing
      window decorations for specific client types.
      </para>

      <para>The framework provides three different theme engines:
      </para>

      <itemizedlist>
	<listitem>
	  <para>MBWMThemeSimple; this is the default engine that uses
	  only basic Xlib API for drawing the window decors. It is built if
	  the PNG theme engine is not enabled via the --enable-png-theme
          configure option.
          </para>
	</listitem>

	<listitem>
	  <para>MBWMThemePng; a theme engine which 'cuts out' window decorations
	  from a single PNG template image. This engine makes it possible to
	  design complex, visually impressive, themes with minimal effort. It
	  needs to be enabled explicitly with --enable-png-theme.
          </para>
	</listitem>
      </itemizedlist>

    </section>

    <section id="MBWMLayout">
      <title>MBWMLayout</title>

      <para>MBWMLayout provides the logic for distributing the screen real
      estate between the managed clients. This is intrinsic to the MBWM2
      management paradigm, and should rarely need to be subclassed when
      designing a custom manager.
      </para>

    </section>

    <section id="MBWindowManager">
      <title>MBWindowManager</title>

      <para>MBWindowManager is the core object representing the window manager
      itself. It provides the essential functionality of the manager, which in
      most cases will be extended through a custom sub-classed object. To this
      end, MBWindowManager exposes a number of virtual methods.
      </para>

      <section id="MBWindowManager-virtuals">
	<title>MBWindowManager Virtual Methods</title>

	<itemizedlist>

	  <listitem>
	    <para>process_cmdline: handles command-line options; if the custom
	    object implements this method, it should chain up to the method
	    provided by it's parent class, so that standard MBWM2 options get
	    handled correctly.
            </para>
	  </listitem>

	  <listitem>
	    <para>client_new: method used to allocate instances of
	    MBWindowManagerClient and its sub-classes; any manager that uses
	    custom MBWindowManagerClient sub-classes must implement this method.
            </para>
	  </listitem>

	  <listitem>
	    <para>layout_new: method used to allocate an instance of the
	    MBWMLayout object; this method needs to be implemented only if the
	    custom WM sub-classes MBWMLayout.
            </para>
	  </listitem>

	  <listitem>
	    <para>client_activate: method used to activate a client; this method
	    only needs to be implemented if the custom WM requires some special
	    action to be taken while activating a client (in which case the
	    custom method should chain up to that of the parent class).
            </para>
	  </listitem>

	  <listitem>
	    <para>client_hang: this method allows the custom WM to handle a hang
	    client in a specific way (the default action is to shut it down);
	    used as part of the ping protocol.
            </para>
	  </listitem>

	  <listitem>
	    <para>client_responding: this method allows the custom WM to handle
	    client's response to a ping in a specific way (the default action is
	    to NOP); used as part of the ping protocol.
            </para>
	  </listitem>

	</itemizedlist>

      </section>

    </section>

  </section>

  <section id="creating-manager">
    <title>Creating a Window Manager</title>

    <para>The component framework provides all the functionality necessary for a
    basic window manager, so that only a dozen or so lines of code are required
    to create one; such a basic manager implementation is provided in
    src/managers/simple.
    </para>

    <para>For a more specialised window manager it will be necessary to subclass
    some of the framework objects. Typically, you will need to provide a
    sub-classed MBWindowManager object (implementing the custom client_new()
    virtual function), and subclasses of MBWindowManagerClient for any client
    types for which customised behaviour is required. An example of a more
    specialised window manager can be found in src/managers/maemo, containing a
    window manager customised to the needs of the Nokia Maemo platform.
    </para>

  </section>

  <section id="designing-themes">
    <title>Theming Matchbox Window Manager II</title>

    <para>The MBWM II theme consists of an XML description and, in case of a
    PNG-based theme, the theme image. There are two distinct theme engines
    provided: a simple engine, using back Xlib drawing primites, and a PNG-based
    engine.
    </para>

    <para>The simple engine is suitable for simple themes with minimal frills.
    The PNG engine, on the other hand, facilitates the creation
    of visually impressive and complex themes; it is based on single template
    image, which contains all the elements the theme consists of, with the
    location of each element is described in the xml description file.
    Essentially, the PNG image can be thought of as a screen shot, or a mockup
    of the screen; however, it does not have to match the size of the screen
    (indeed, in order to save HW resources, the image should contain minimum of
    'dead' space).
    </para>

    <para>
    PNG themes can also use shaped windows; any transparent pixels in any of the
    decorations will be excluded from the window shape (as long as the both the
    theme and the relevant client is marked as using shaped windows in the XML
    description).
    </para>

    <para>The XML theme description uses the following elements:
    </para>

    <section id="element-theme">
      <title>theme</title>

      <para>The top level element of the theme, with the following attributes:
      </para>

      <itemizedlist>

	<listitem>
	  <para>name: name of the theme.
          </para>
	</listitem>

	<listitem>
	  <para>author: name of the author.
          </para>
	</listitem>

	<listitem>
	  <para>desc: longer description of the theme, e.g., for display in a
	  GUI theme switcher.
          </para>
	</listitem>

	<listitem>
	  <para>version: version of the theme.
          </para>
	</listitem>

	<listitem>
	  <para>engine-version: must be "2" for MBWM2.
          </para>
	</listitem>

	<listitem>
	  <para>engine-type: type of theme engine preferred by this theme;
	  legitimate values are "png" and "default" (default is "default").
          </para>
	</listitem>

	<listitem>
	  <para>compositing: whether composting should be enabled for this
	  theme; "yes" or "no", default "no".
          </para>
	</listitem>

	<listitem>
	  <para>shaped: whether this theme uses shaped windows; "yes" or
	  "no", default "no" (only available for PNG themes; see the "client"
	  element for more information).
          </para>
	</listitem>

      </itemizedlist>

      <section id="element-img">
	<title>img</title>

	<para>The img element specifies the source image for a png theme; it
	will be ignored if the png engine is not used. It has the following
	attributes:
        </para>

      <itemizedlist>

	<listitem>
	  <para>src: the name of the image, which will be looked for in the same
	  directory from which theme description has been loaded.
          </para>
	</listitem>

	</itemizedlist>

      </section>

      <section id="element-client">
	<title>client</title>

	<para>The client element specifies theming requirements for a client
	type; any client types that are not specified will be handled with the
	defaults of the theme engine for that particular client type.
        </para>

	<para>The client element has the following attributes:
        </para>

	<itemizedlist>

	  <listitem>
	    <para>type: the type of client to which this description applies;
	    legal values are "app", "dialog", "panel", "input", "desktop",
	    "notification" (client of type MBWMClientTypeMenu and
	    MBWMClientTypeOverride cannot be themed).
            </para>
	  </listitem>

	  <listitem>
	    <para>shaped: whether this client uses shaped windows; "yes" or
	    "no", default "no". (Shapped windows are only supported with PNG
	    themes, where the invisible parts of the decorations are
            transparent in the theme image.)
            </para>
	  </listitem>

	  <listitem>
	    <para>x, y, width, height: geometry for the client. (Note that for
	    most client types it makes little sense to specify geometry in the
            theme, and the values will be ignored. The notable exception to this
	    are panel clients, the position and size of which might be
	    theme-dependent, as for example, with the maemo status bar.)
            </para>
	  </listitem>

	</itemizedlist>

	<section id="element-decor">
	  <title>decor</title>

	  <para>The decor element specifies how its parent client should be
	  decorated. It has the following attributes:
          </para>

	  <itemizedlist>

	    <listitem>
	      <para>type: the decor type; legal values are "north", "south",
	      "east", "west".
              </para>
	    </listitem>

	    <listitem>
	      <para>show-title: whether the client title (such as window name)
	      should be displayed on the decor; legal values are "yes", "no",
	      default is "no".
              </para>
	    </listitem>

	    <listitem>
	      <para>template-x: for PNG-based themes this is the the x coordinates of the
	      decor in the image; ignored for other theme engines.
              </para>
	    </listitem>

	    <listitem>
	      <para>template-y: for PNG-based themes this is the the y coordinates of the
	      decor in the image; ignored for other theme engines.
              </para>
	    </listitem>

	    <listitem>
	      <para>template-width: width of the decor. For PNG themes this value has to
	      be given explicitly, and is the width of the decor in the image
	      (if actual decor is wider than this value, the image will be
	      expanded by tiling the middle section); for other themes, it has
	      to be given for east and west decors (for north and south decors
	      width is implied and the attribute will be ignored.)
              </para>
	    </listitem>

	    <listitem>
	      <para>template-height: height of the decor. For PNG themes this value has
	      to be given explicitly, and is the height of the decor in the
	      image (if actual decor is taller than this value, the image will
	      be expanded by tiling the middle section); for other themes, it
	      has to be given for north and south decors (for east and west
	      decors height is implied and the attribute will be ignored.)
              </para>
	    </listitem>

	    <listitem>
	      <para>template-pad-offset: for PNG-based themes this is an offset
              (from template-x for "north"/"south" decors or template-y "east"/"west"
              decors) to a segment in your template image that can be used to pad the decor
              when it is wider/taller than the underlying template image. As well as
              locating the template data to copy for padding it also specifies the position
              at which padding is inserted.
              </para>
	    </listitem>

	    <listitem>
	      <para>template-pad-length: for PNG-based themes, used in conjunction with
              the template-pad-offset attribute, this specifies the length of the segment in
              your template image that is used for padding decors that are wider/taller than
              your template image.
              </para>
	    </listitem>

	    <listitem>
	      <para>font-family: the font to be used for any text display on the decor.
              </para>
	    </listitem>

	    <listitem>
	      <para>font-size: the size of font to be used for any text display on the decor.
              </para>
	    </listitem>

	    <listitem>
	      <para>color-fg: the foreground colour to use.
              </para>
	    </listitem>

	    <listitem>
	      <para>color-bg: the basic background colour. If a background color
	      is specfied for a PNG based theme, the decor will be first filled
	      with this color, and then the PNG image will be composited over
	      it; in this case, the images for any buttons must be located of
	      the decor, and the "inactive-x", "inactive-y" of the "button"
	      element used.
              </para>
	    </listitem>

	  </itemizedlist>

	  <section id="element-button">
	    <title>button</title>

	    <para>button element describes a button that belongs to its parent
	    decor; it has the following attributes:
            </para>

	    <itemizedlist>

	      <listitem>
		<para>type: type of the button; legal values are "minimize",
		"accept", "close", "menu", "fullscreen", "help".
                </para>
	      </listitem>

	      <listitem>
		<para>packing: "start" or "end". Whether the button should be
		packaged from start or end of the decor, default "end"; this
		parameter is ignored for PNG themes (in which buttons are placed
		explicitely, see below).
                </para>
	      </listitem>

	      <listitem>
		<para>template-x: for PNG-based themes this is the the x coordinates of
	        the button in the image; the button must be located directly on
	        the parent decor. Ignored for other theme engines.
                </para>
	      </listitem>

	      <listitem>
		<para>template-y: for PNG-based themes this is the the y coordinates of
	        the button in the image; the button must be located directly on
	        the parent decor. Ignored for other theme engines.
                </para>
	      </listitem>

	      <listitem>
		<para>width: width of the button.
                </para>
	      </listitem>

	      <listitem>
	        <para>height: height of the button.
                </para>
	      </listitem>

	      <listitem>
		<para>template-inactive-x: for PNG-based themes this is the the x
	        coordinates of the button in inactive state in the image;
	        ignored for other theme engines. (The inactive image can be
	        located directly on the decor image, in which case, this
	        parameter is unnecessary.)
                </para>
	      </listitem>

	      <listitem>
		<para>template-inactive-y: for PNG-based themes this is the the y
	        coordinates of the button in inactive state in the image;
	        ignored for other theme engines. (The inactive image can be
	        located directly on the decor image, in which case, this
	        parameter is unnecessary.)
                </para>
	      </listitem>

	      <listitem>
		<para>template-active-x: for PNG-based themes this is the the x
	        coordinates of the button in active state in the image; ignored
	        for other theme engines.
                </para>
	      </listitem>

	      <listitem>
		<para>template-active-y: for PNG-based themes this is the the y
	        coordinates of the button in active state in the image; ignored
	        for other theme engines.
                </para>
	      </listitem>

	      <listitem>
		<para>press-activates: "yes" or "no"; whether the button
		responds to a press of the pointer, or its release.
                </para>
	      </listitem>

	    </itemizedlist>

	  </section>

	</section>

      </section>

    </section>

  </section>

  <?hard-pagebreak?>

  <section id="contact">
    <title>OpenedHand Contact Information</title>

    <literallayout>
OpenedHand Ltd
Unit R, Homesdale Business Center
216-218 Homesdale Rd
Bromley, BR1 2QZ
England
+44 (0) 208 819 6559
info@openedhand.com</literallayout>

    <!-- Fop messes this up so we do like above
    <address>
        OpenedHand Ltd
        Unit R, Homesdale Business Center
        <street>216-218 Homesdale Rd</street>
        <city>Bromley</city>, <postcode>BR1 2QZ</postcode>
        <country>England</country>
        <phone> +44 (0) 208 819 6559</phone>
        <email>info@openedhand.com</email>
    </address>
    -->
  </section>

</article>