User's Documentation

Laurent Orseau edited this page Sep 30, 2017 · 7 revisions

You may also be interested in the developer's documentation.

User Documentation

For installation instructions and a quick start, refer to the README.

The Main Panel (Toolbox)

To start, you can create a project (File > New Project), in which you can add frames, in which you can add buttons, check-boxes, panels, other frames and other containers, etc. Just click on the corresponding buttons.

Once you're happy with it, you can generate the Racket code -- a module -- either directly in the console or saved in a file. Once you require this module and call the project specific init function, the same frames that you defined should appear.

Several projects can be opened at the same time (useful for copy/paste between different projects).

The Hierarchy Panel

In the hierarchy panel, you can rearrange the widgets. Move them up or down, or cut/copy/paste them from one node to the other.

The Properties Panel

When you click on an widget in the frame, its properties are displayed in the property panel. You can modify them to suit your needs.

IMPORTANT: Don't forget to click Update Preview to see the changes (in most cases, you can also press Enter).

In general, it is a good idea to change the id of each widget to give it an informative one.

For general information about the fields, please refer to Racket GUI documentation.

The left check-box

On the left of each field, there is a check-box. Check it if you want the corresponding field identifier to be an optional argument of the initialization function in the generated code. For example, suppose you have a button named `my-button' and the callback is checked. Generate the .rkt file of your project. Then call the init function with something like:

      (lambda (b e) (displayln "Button pressed!")))

Then press the button...

As a special case, when an id check-box is checked, the corresponding identifier is provided by the generated module. By default, callbacks are checked, as well as ids for frames and dialogs, so that they can be given at call time.


If you check this (left-)check-box, the class of this widget in the generated code will be a keyword optional argument of the init function. This is useful for example if you want a frame that augments on-close. Check this box, then when calling the generated initialization function, do something like:

      (class my-frame% (super-new)
        (define/augment (on-close) (displayln "Closing..."))))


For frames and dialogs, the show-at-init property defines whether the frame/dialog is shown when the generated function is called. By default, it is true for frames, and false for dialogs.


When a project is selected, you can see a code-requires property. This list is the module names that will be added to the require form in the project's generated Racket file.


A project also has a runtime-paths? property. Check this box if you want all paths in the generated code to be defined with runtime-path.

x, y, width, height

These properties have a check-box and a text-field where a number can be entered. The number value is taken into account only if the box is checked, otherwise the value is #f (which is useful to let the frames/dialogs be placed automatically).


A label property is usually a text-field, but can also have a check-box and a button to choose an image, e.g., for button%s and message%s. The image is taken into account only if the box is checked, otherwise the label uses the text-field value.

File paths (like images) are always relative to the .med project file, even if it is not in a direct sub-directory.

Images are loaded with the 'unknown/mask flag for transparency.

To use runtime-paths in the generated code, check the runtime-paths? box in the project properties.


Templates a useful widgets or compound widgets that you may reuse from time to time. Suppose you have made a form as a group-box with several buttons, check-boxes and text-fields, and you think you may use it at several places. Just click on the group-box, click Save in the template group and enter a descriptive name. Now your new template should appear in the template list.

If you want to paste a template somewhere else, say in another frame, just select that frame or node, select the template in the list and click insert.

Templates are also useful to give different default values to widgets.

If you think you have made a useful template, please don't hesitate to send it to me, I may integrate it in the next release.

Plugins (for experimented users)

If you need a specific widget that cannot be made with templates, then you may need a plugin. This needs a little programming.

In the widgets folder of MrEd Designer, you can see all the default widgets, which are in fact treated as plugins.

To add a plugin, create a new folder, e.g. my-widget. In it, create a widget.rkt file and an icon folder with two images: 16x16.png and 24x24.png (images for the widget plugin button in the Toolbox and for the icon in the Hierarchy Panel). Or just copy an existing plugin, like check-box.

In widget.rkt the one form that must be called is make-plugin.

The first set or arguments describe the plugin. The second set are the default widget properties (property fields).

Plugin Arguments

  • type: a symbol resembling the name of the "my-widget" folder
  • tooltip: the text that will appear when hovering over the widget plugin button in the Toolbox
  • button-group: the group box in which will appear the plugin button (existing ones are "Containers", "Controls" and "Menu"). Use #f if you don't want a button
  • widget-class: the class that will be instantiated to create the widget in the user frame
  • code-gen-class: the widget class used in the generated code (default = widget-class)
  • parent-class: the class under which the widget can be instantiated. Except for widgets like frames and menus, in general you can use container-classes (default = #t, i.e. all class is acceptable as a parent, even no parent)
  • necessary: the set of property fields that are necessary when instantiating such widget. Not used right now (default = '())
  • options: the set of property fields that will be an option by default in the generated code. This can be changed by the user in the Properties Panel (default = '(callback))
  • no-code: the set of property fields that will not be included in the generated code (default = '() but 'id and 'code-class are included automatically)
  • hidden: the set of property fields that will be hidden in the Property Panel (but can still be written in the generated code) (default = '())

In some cases, you will need to create one class for the "preview" widget in MrEd Designer, and another one for the "real" widget in the generated code. You can use the optional code-gen-class field to specify that "real" class. See the example for the frame widget plugin.

Widget Property Fields

The last set of arguments are fields that are applied to the `new' call with the widget class, and so depends on the widget class.

The right part of a field can be either a simple value (#t, 123, "Hello", '("a" "b" "c"), etc.) or a property%. Simple values will in fact be turned automatically into property%s.

Simples values will be displayed in the Property Panel with the following:

  • #t or #f: check-box
  • string: text-field
  • symbol: text-field (but the returned value will still be a symbol)
  • number: text-field that accepts only numbers
  • list (of strings): a specific widget that allows to edit the values of the list

In addition, more complex property%s can be used (yes, the "prop:" prefix is a bad choice...):

  • (prop:bool <label> <value>): A check-box with a label.
    • <label>: string?;
    • <value>: boolean?
  • (prop:file <file>): A button to ask for a file.
    • <file>: (or/c #f path-string?)
  • (prop:one-of <choices> <value>):Proposes a list of choices with default value.
    • <choices>: list?
    • <value>: any
  • (prop:some-of <choices> <values>): Proposes a list a checkable items, where the 'values' are checked by default.
    • <choices>: list?
    • <values>: list?
  • (prop:group <props>): Groups several properties. The resulting value will be a list of values.
    • <props>: (list-of property%)
  • (prop:popup <prop>): Displays a button that when pressed will ask for the corresponding property. Useful with prop:group.
    • prop: property%
  • (prop:code <code>):The resulting value will be written literally. Use this for, e.g., callbacks. This property is not displayed in the Property Panel.
    • <code>: any
  • (prop:proc <prop> <proc>):Once prop has returned a value from the user, this value is applied to proc and the result is the real value given to the field. The prop:proc function is very useful to ask to transform the result of other properties into a value that is acceptable by the field.
    • <prop>: property%
    • <proc>: procedure?

There are predefined compound widgets (defined in "default-values.rkt"):

  • (font-values): used for the font field
  • (alignment-values): used for the alignment field
  • (label-bitmap-values "something"): a compound widget to ask either for a label or for an image file
  • (shortcut-values [<value>]):Asks for a shortcut from a list. Value is the default shortcut (#f by default, optional).
    • <value>: (or #f char? symbol?)

See the existing widget plugins for usage examples.

If by chance you happen to make a new plugin, please send it to me, I'm interested!

Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.