GLAYOUT - User Guide

Chapter 1: THE BASICS

Chapter 2: THE LAYOUT SYSTEM

Chapter 3: THE DIALECT AND RUN-TIME EDITING

Chapter 4: STYLE GUIDE AND VISUAL TRICKS

Chapter 5: HIDDEN SECRETS REVEALED !

Chapter 6: THEMES WITH LUSTER

Chapter 7: LOCALES

Chapter 8: REQUESTORS

Chapter 9: THE GLAYOUT MODULE

Chapter 10: GLITTER

Chapter 11: CREATING CUSTOM STYLES

1.1. Based on VID.

GLayout is actually using the VID dialect internally, so the major concepts of VID apply to GLayout too. Things like styles and the way you assign data and setup individual faces is the same.

1.2. Dynamic layout engine.

Where GLayout sets itself appart is in the way it aligns faces, which is radically different and wholly incompatible to VID. The second main difference is in the fact that is is 100% dynamic and supports window resizing without you having to supply any sizing values or having to calculate complex alignment.

You don't even have to manually attach edges or determe sizing relative to window or other gadgets.

1.3. Requestors

Some requestors have been re-implemented using GLayout so as to make them more intuitive and more flexible. A noteworthy example is the file requestor.

Eventually, all requestors will have an refurbished equivalent in GLayout.

2.1. Description

Faces and styles within GLayout are often refered to as Gadgets.

These can be controls which actualy react to user events or simple display items, like text and graphics boxes.

You create gadgets just like with normal VID, by specifying a block of words and values. Most facets still exist, but some are replaced or ignored, specificaly where layout is concerned.

2.2. Alignment and x/y independance.

Gadgets have many attributes which let the layout know how they wish to be handled, or how they profit from extra space or dynamicity. Things like default sizes, minimum sizes, static sizes, various re-sizing modes. All of these attributes will be described in chapter 2 In detail.

Gadgets do not know how to align themselves, so they rely on the groups (described below) to do it for them.

For Gadgets to be really flexible, GLayout handles all X and Y part of any alignment or sizing coordinates separately. This means a gadget can stretch in one direction and be staticaly sized in the other.

Each gadget type defines the default values which are meant to be ideal in the vast majority of cases. Nice thing is that you can try to overide these, when such changes are appropriate.

3.1. Description

Groups are panes of gadgets, which understand how to allocate space to their children.

Most of what applies to gadgets also applies to Groups, as groups are based on gadgets, but have a completely different mission.

3.2. group direction and coordinates

All groups have a direction. Either Horizontal or Vertical.

when talking about coordinates which are in the same direction as the group's direction, we say that those coordinates are stretch coordinates. This means that x is the stretch coordinate or direction of any horizontal group and y is the stretch coordinate or direction of any vertical group.

The other coordinate is called the Fixed coordinate, y for horizontal groups and x for vertical groups. This Does not mean that gadgets will be statically sized in this direction, but rather that in this direction there is no individual stretching, all faces share the Fixed size of the group they are in.

3.3. Special Groups

There are many derived group styles. These act exactly like groups but might have more explicit visual setups, or might act like super Groups with added functionality. Examples are vpanes, vforms, vblk, etc. We will be looking at these in detail later on.

4.1. Alignment

Face alignment is basically achieved by Groups which stack all the faces they contain next to each other in their stretch direction. Every gadget can be of a different size within the stretch direction. The second noteworthy aspect of alignment is that all the faces in a group share the same Fixed size. They are all equal in size to the group's fixed size.

4.2. Group hierarchy

By nesting groups within groups, you will eventually be able to create any combination of aligned faces.

The direction of groups and their child groups is completely irrelevant. This means you can have vertical or horizontal groups as children of vertical or horizontal groups.

1.1. The Two different phases of resizing

Spatial requirements calculation

Here, the engine traverses the whole layout tree (or subregion if called on a specific face) and asks everyone for the amount of space they need in various conditions.

The engine also compiles the values of elasticity and stretching that groups need in order to support re-sizing later on.

Spatial allocation

Once the engine nows how much it needs or wants, it has to know what to do with what it HAS. Meaning, it actually tells each face just how much space it has to start drawing itself.

It could have more than needed or less than asked for, yet more than the absolute minimum space required.

The whole tree is traversed, until each face has been refreshed at their new size.

1.2. Speed considerations

The reason calculation and allocation are separated is purely performance related.

That is because, you only need to calculate needs once, yet will need to re-allocate area everytime the window is re-sized.

1.3. How does hierachical sizing propagate?

Basically each group compiles its contents's needs and sends it to its own parent.

This includes how much elasticity (if any) and stretching (if any) is needed by the window.

Then when there is a layout called, each panes gest back the same amount it asked for.

If a group gets more space than it needs, then it is responsible for allocating that extra space amongst its children. Yet rememeber that it can only receive extra space, if it actually mentioned that it, or one of its children was able to support it.

2.1. A face will never be smaller than its minimum size parameter

This is a core functionality of GLayout, and if you ever get a face with a face size less than its minumum, you can report it as a bug.

2.2. Elasticity is more usefull than stretching

If any gadget in a layout is elastic in one or both directions, any available stretch of shrink space will be allowed to them in preference to any other space.

2.3. Different sizing rules for sizing larger or smaller than default size

This is simply so that elastic gadgest always retain the most GUI space in preference to those who don't really need it.

3.1. Default size

face/def-size

Probably the most basic sizing attribute, def-size will tell GLayout what it considers a typical size for itself. This size is considered to usually yeild the nicest GUIs, so try to use this if possible.

3.2. Static size

face/static-size

This is the equivalent of how you are used to doing it in vid. By selecting This, you acknowledge that you do NOT want this gadget or group to resize in any way.

Setting this value after a calc-sizes has been called can be hazardous to the way the locale will be done. note that if both sides of the static resizing are set, it wont resize even in the fixed direction.

3.3. Static resizing

Within dialect spec only

This is useful for things you don't want to guess the size of, but also don't want to react to window resizing, cause it would be annoying. A good use for this is within button groups, where you'd want all buttons to align to the largest, but there is no point in the buttons scalling afterwards.

3.4. Minimum size

face/min-size

As discussed earlier, this is the absolute minimal size the face can be when resized.

3.5. Stretching

face/stretch

Stretching, is pretty simple. When there is extra space for a group and its contents can share, just separate all the extra space evenly amongst siblings by giving each one a relative weight equivalent to the value set in each direction.

Setting a value in the Fixed direction will propagate the weight to the group (keeping the largest weight) and then the group will be properly scaled wrt its peers... this propagates up to the top level faces...

As an example, if you want one gadget to use up twice the amount of extra free space than its peer, then set its stretching to 2 in the stretchin direction and leave it at one for all others.

3.6. Elasticity

face/elasticity

Elasticity functions in the exact same way as the stretching with a big philosophical difference. Any elastic face is meant to benefit from any extra space it gets.

Purely stretching face merely follow any resizing, but don't truely benefit from its extra space, they just align properly and allow a resizable window.

Example: The text-entry field

The text-entry field is a good example for a case study. In the horizontal direction, the field is elastic. In the vertical direction, it is only strech enabled. This means that if you do a layout with only a field in it, the field will try to use up all the horizontal space in can get, yet will only occupy more vertical space if it is placed next-to another gadget which is taller.

3.7. Shrinking

This is somewhat like stretching, but occurs when the layout is SMALLER than the default size, yet still larger or equal to the minimum size.

Again, here, elastics have priority, and any elastic shapes share the extra space which is left from minimum size between themselves.

This means that when shrinking occurs all stretch enabled faces will shrink BEFORE the elastic ones do. When all stretch faces are at minimum size, then the elastic faces will also start to shrink.

3.8. Size attribute

face/size

So, this all being said, the actual face/size parameter is pretty useless, as it will be refresh at will at each window resize. You should not use it, instead set the default size of you control and that's how it will open... it the window is not resizable, then the GUI still looks good.

3.9. What about Maximum size?

I did not include such capabilities in an attempt to simplify its design for the inital releases.

Each sizing attribute is in competition with the other attributes and each face is in competition with the other faces. When you mix all of that up, you end up with a pretty complex system. By experience, maximum is by far the least usefull sizing attribute, so simply skipped it. in an eventual release, I plan on adding it, but there are so much more important things to add before.

3.10. What about Margins, padding and automatic spacing?

These are all noble layout attributes, but again, implementing them would mean a lot of additional head aches for which I am not prepared to face. In the release 2 of the layout engine itself, I will surely add many layout candies like the above...

The spacing attributes, all have workarounds by using spacers. I'm not saying its beautifull, only that its easy to replicate, so I'd rather add the more powerfull features like the theme engine first.

The following alignment gadgets allow workarounds which imitate any of those attributes, although they do add some complexity to the layout, cause you will have to add nested groups just to allow spacing AROUND a gadget or group.

4.1. spacer

There is a spacer gadget which is responsible for placing a little bit of breathing space in between gadgets. All it does is occupy space and is completely visually invisible.

The neat thing about this face is that by default, it will Shrink down to almost nothing if the layout is severely shrinked. This means that your GUI can be very elastic in size, and it will always try to allocate precious window space to gadgets which need it.

4.2. elastic

The Elastic is a special style which only makes sure that adds elasticity to a group, without actually having to have an elastic gadget within it.

A good example of where is usefull to have an elastic, is at the end of a text list which might be smaller than the group it is... if you don't supply an elastic as the last item of the list, then all items in the list, will share the space of that group instead of being tightly packed at the top, with an amount of free space below them.

4.3. filler

A filler is somewhat like an elastic, except that it does not create elasticity for the group, so that you still can't resize the window larger than needed.

The filler is cool to center stuff, by just putting a filler on each side of a gadget or group, you effectively center it within its parent. This is especially usefull for fixed-sized items which must stay the same size even though their parent group might resize or contain elements which are of a larger size.

Note: take care of these alignment issues only at the end of your layout prototyping, as they add unnecessary complication to your layout, until they are really needed...

5.1. hgroup / vgroup

These are the basic styles which are responsible for all the dynamicity of the layout itself. Part of the Group styles, is the layout engine itself.

All the faces a group contains are stacked in the direction of that group, the first letter being the direction, H for horizontal and V for vertical. You'll notice that all the following panes have the same duality.

5.2. hpane / vpane

The Pane groups are a sunken (ibevel) group, they behave exactly like a normal group, but have different layout looks.

5.3. hform / vform

The forms are pretty much the same except that they are beveled instead.

5.4. hblk / vblk

The blk groups are another pair of groups which have a simple black outline they are often used to add contrast to other forms or groupings.

Adding a blk group greatly enhances the look when it is immediately included within or outside another face, kind of like a wrapper.

1.1. Nesting groups

here is is a quick example of a layout which is nested.

gl/view [
  vgroup [
    header "really quit?"
    hgroup [
      button "ok"
      button "save"
      button "cancel"
    ]
  ]
]

horizontal group within a vertical group

You can easily see that this layout includes two groups, one within the other.

You should note that groups do not have to be included in alternating order... you could also have written this:

gl/view [
  vgroup [
    header "really quit?"
    vgroup [
      button "ok"
      button "save"
      button "cancel"
    ]
  ]
]

vertical group within a vertical group

There is no limit to the dept at which you can go to create your layout.

1.2. Things in VID which are not available

None of the layout words like accross, below, return, etc can be used in glayout.

2.1. Changing the size of a group

2.2. Changing the size of a gadget

2.3. Recalculating the layout and re-allocating space

0.1. Creating soft edges

0.2. using elastics

0.3. create a selection list

1.1. saving out your GUI as an image on disk

Intended as a permanent feature, with a temporary setup and featurelist, this is every usefull to send out screengrabs of your apps to document OR to supply as a complement to a bug report

Whenever you press on SHIFT + F8 , a requester will appear asking you to save out a png version of your current GLayout GUI window!

1.2. Using GLayout resource folder to create a window edge around the captured GUI before it is saved out.

It is much more intuitive for someone receiving or viewing a gui capture, if there is a window border to it. To this end, I have added support for this by looking for files within the GLayout resource folder (rsrc-glayout) which should be created in the same folder as the GLayout module which is being used:

rsrc-glayout/snapshot-windows-title.png

rsrc-glayout/snapshot-windows-bottom-edge.png

rsrc-glayout/snapshot-windows-left-edge.png

rsrc-glayout/snapshot-windows-right-edge.png

Note That you must have all images or none, otherwise GLayout will fail on startup.

Curently, the image sizes are set in stone, thus if you need to support this feature, ask author about these files on the REBOL altme world or REBOL Mailing world and he will gladly send you images for a windows border.

Luster is still in prototyping stage , but I included it in the docs, so that you know what to expect when it will be available.

You can change application Luster at any time. The GUI will react in real time and simply cause one refresh. All the Gadgets and groups which support Luster will then switch to the style you chose.

Changing the configuration of a Luster on disk will also be reflected the next time you switch luster, this is done by verifying the date of the Luster folder you are switching to. if it is more recent than the one you last loaded, it will be reloaded.

2.1. Switching the default Luster.

2.2. Changing Luster components on the Fly!

0.1. not yet available.

Will be included by year's end. Just after Luster is completed.

1.1. Switching the default Luster.

1.2. Changing Luster components on the Fly!

0.1. What is GLitter?

GLitter is a procedural styling system. It is meant to be live and handles dependencies when some aspects of styles are shared and reused amongst many styles. Using GLitter you can change a theme, or a Locale or YOU can customize just how an application will look, if it allows it.

0.2. How does it work?

Basically, it just applies style and facet setup on demand.

Because you can link up more than one GLitter to a face, this means that you can apply several concurrent styles independentaly.

Because the system is also nondescript, you or the author of a theme, is not completly bound by a strict api. You can separate stuff within your GLitters between several sub GLitters. There really is no limit, but reasonable rendering speed should be observed.

last updated: 17-Sep-2004/5:38:18-4:00