[[PageOutline(1-2)]]

= Widgets =

[[Image(widgetsbanner.PNG, nolink)]]

Adds nice looking Morphic controls, e.g., lists, dropdown lists, push buttons, check boxes. It uses the [wiki:signals] mechanism for callbacks.

= How to Install =
{{{
#!div class="wiki_infotable" style="float:right;"
||'''Environment'''|| ||
|| [[Image(media/icons/custom:squeak_16.png, title="Recommended Squeak Version", nolink, right)]] || 4.1, 4.2 Trunk ||
|| [[Image(media/icons/silk:application_home.png, title="Recommended Squeak VM Version", nolink, right)]] || 4.0.2 (win) ||
|| [[Image(media/icons/silk:cog.png, title="Recommended Cog VM Version", nolink, right)]] || r2316 ||
||'''Sources'''|| ||
|| [[Image(media/icons/silk:script_gear.png, title="Metacello Configuration", nolink, right)]] || [http://www.hpi.uni-potsdam.de/hirschfeld/squeaksource/MetacelloRepository/ ConfigurationOfWidgets] ||
|| [[Image(media/icons/silk:database.png, title="Repository", nolink, right)]] || [http://www.hpi.uni-potsdam.de/hirschfeld/squeaksource/SwaUtilities/ SwaUtilities] ||
|| [[Image(media/icons/silk:package.png, title="Needed Packages from the Repository", nolink, right)]] || Widgets ||
|| [[Image(media/icons/silk:package.png, title="Needed Packages from the Repository", nolink, right)]] || Icons (optional) ||
|| [[Image(media/icons/silk:bullet_go.png, title="Dependents", nolink, right)]] || [wiki:signals Signals] ||
|| [[Image(media/icons/silk:bullet_go.png, title="Dependents", nolink, right)]] || [wiki:animations Animations] ||
|| [[Image(media/icons/silk:bullet_go.png, title="Dependents", nolink, right)]] || [http://www.squeaksource.com/Regex VB-Regex] ||
||'''Misc'''|| ||
|| [[Image(media/icons/silk:world.png, title="Website", nolink, right)]] || [http://www.hpi.uni-potsdam.de/hirschfeld/squeaksource/SwaUtilities.html SwaUtilities@SqueakSource] ||
}}}

Using Metacello, just run the following code in your workspace: 

{{{
(Installer mc http: 'http://www.hpi.uni-potsdam.de/hirschfeld/squeaksource/')
   project: 'MetacelloRepository';
   install: 'ConfigurationOfWidgets'.
ConfigurationOfWidgets load.
}}}

If you want to update to the latest development version, run this:

{{{
ConfigurationOfWidgets loadDevelopment.
}}}

'''Configuration groups'''

{{{default}}} ... just the widgets[[br]]
{{{full}}} ... widgets and several CC icon sets (~10000 icons)[[br]]

'''System categories'''

{{{Widgets-Core}}} ... various widgets (e.g., buttons, lists, line inputs)[[br]]
{{{Widgets-Support}}} ... internally used helper classes[[br]]
{{{Widgets-Views}}} ... model-based item views (list, table, tree with columns)[[br]]
{{{Widgets-Views-Models}}} ... example models also used in default dialogs[[br]]
{{{Widgets-Views-Support}}} ... internally used helper classes for item views[[br]]
{{{Widgets-Dialogs}}} ... default dialogs, ui files created with [wiki:designer Morphic Designer][[br]]

'''Version 1.1 (in development)'''

 * dependency from SwaUtil removed
 * improved item-based and model-based views
 * to be used in [wiki:designer Morphic Designer 1.1]
 * new property for buttons: `enabled`
 * `UiTextEdit` works

'''Version 1.0'''

 * first release to be used in [wiki:designer Morphic Designer 1.0]
 * still dependent from [wiki:swautil] due to text formatting functions
   * will be removed soon as lots of other stuff comes with that package
 * some example dialogs need the ''Icons'' package

{{{
#!div style="clear:both;"
}}}

= How to Use =

== Buttons ==

'''Common Properties'''
|| '''Selector'''  || '''Type''' || '''Description''' ||
|| `autoExclusive` || Boolean || only one of these in the owner is checked at a time ||
|| `checkable` || Boolean || determines whether it can be `checked` or not ||
|| `checked` || Boolean || button remains in a visual down state if true ||
|| `enabled` || Boolean || controls (mouse) input in general ||
|| `icon` || Form || appearance depends on the button type ||
|| `text` || String or Text || text written on the button ||

'''Push Button'''

[[Image(pushbutton.png, nolink, title="A simple push button with an icon.")]]

A push button is the most known and used button type. It is often used for ''OK'' and ''Cancel'' operations in a dialog.

'''Tool Button'''

[[Image(toolbutton.png, nolink, title="Three tool buttons in a row. The middle one is checked.")]]

|| '''Selector'''  || '''Type''' || '''Description''' ||
|| `autoRaise` || Boolean || raises only on mouse hover if true ||
|| `buttonStyle` || Symbol || determines the layout and usage of `icon` and `text`[[br]]`#iconOnly`, `#textOnly`, `#textBesidesIcon`, `#textUnderIcon` ||

A tool button can be found in tool bars or other places that want to offer functionality in the GUI without having a too much present push button there as the tool button is smaller in general.

'''Check Box '''

[[Image(checkbox.png, nolink, title="Two check boxes. One is checked.")]]

A check box is a checkable button by default with a slightly different appearance as a small button-like square is in front of the text/icon.

== Containers & Spacers ==

'''Common Properties'''
|| '''Selector'''  || '''Type''' || '''Description''' ||
|| `color` || Color || background color ||
|| `borderWidth`  || Integer || the width of the border if not transparent
|| `borderStyle2` || Symbol || `#simple` (uses `borderColor`), `#inset`, `#raised` ||
|| `borderColor` || Color || border color ||

'''Button Group'''

[[Image(buttongroup2.png, nolink, title="Three autoexclusive check-boxes in a container.")]]

This container is for ''buttons only''. For every new button, it automatically enables `autoExclusive` and `checkable`, so 
that only one button can be checked at a time.

'''Spacer'''
|| '''Selector'''  || '''Type''' || '''Description''' ||
|| `orientation` || Symbol || `#horizontal`, `#vertical` ||

[[Image(spacer.png, nolink, title="A spacer widget is only visible in the designer.")]]

A spacer is used to manually separate widgets from each other. The designer draws a thin blue line according to the orientation.

'''Widget Container'''

[[Image(container.png, nolink, title="Four composed widget containers with different border styles.")]]

A widget container is the main layout element for UI designs. If no color is set, it will be transparent in general and get a light gray background for the designer.

Widget container can have ''Table Layouts'' and ''Proportional Layouts''. By choosing one of these modes, all child widgets get new options like `#disableTableLayout` or the offset and frames that specify the proportions.

== Input Widgets ==

'''Combo Box'''
|| '''Selector'''  || '''Type''' || '''Description''' ||
|| `readOnly` || Boolean || Specifies whether only list items can be selected or any text is allowed as input. ||

[[Image(combobox.png, nolink, title="(left) A read-only combobox expanded. (right) A writeable combobox expanded.")]]

A combo box allows you to make a single list choose but hide the list for the rest of the time. UI space is saved.

'''Text Edit'''
|| '''Selector'''  || '''Type''' || '''Description''' ||
|| `theText` || String or Text || the contents of this editable widget ||
|| `readOnly` || Boolean || editable or not; selections work always ||
|| `outerBorderWidth` || Integer || width of the additional rounded outer border ||
|| `autoConvert` || Boolean || convert the contents as you type specified by a ''validation block'' ||
|| `autoAccept` || Boolean || always signals the changed contents as you type - no focus switch or return keypress needed ||
|| `validator` || Block || specifiy the validator; block accepts one parameter (the contents/text) and needs to return a String or Text ||

[[Image(textedit.png, nolink, title="Text edit with contents larger than the widgets -> vertical scrollbar appreas.")]]

This widget improves the classic `PluggableTextMorph` as it supports a read-only mode, input validation, and [wiki:signals].

'''Line Edit''' ''(specialized Text Edit)''
|| '''Selector'''  || '''Type''' || '''Description''' ||
|| `helpText` || String || non-selectable text that appear if no regular text is set ||

[[Image(lineedit.png, nolink, title="A line edit with no contents but the help text visible.")]]

This widget supports only one line of editable text that scrolls automatically on the horizontal axis.


== Display Widgets ==

== Item Widgets (Item-Based) ==

== Item Widgets (Model-Based) ==

= How to Extend =

Most of the widgets are written from scratch. If you want to extend or add new ones, here are some hints:

 * layouting of morphs in combination with embedded text morphs can be problematic in the first place as the dimensions are not correct
   * see optimizations and fixes in `UiComboBox`
 * put all [wiki:signals signals] of a widget class into the ''signals'' protocol
 * for each signal, explain with a comment when it will generally be sent, e.g., ''"This signal is emitted whenever the user clicks with the left mouse button."''
 * try to write as compact classes as possible, i.e., avoid having several classes for buttons, buttons with icons, buttons with icons and text, but write exactly one class and make these features configurable
 * consider the [wiki:designer Morphic Designer] and implement on the class-side of your widget class:
   * `#isWidgetClass` ... used by the designer as a widget
   * `#widgetCategory` ... as grouped in the designer's widget tree
   * `#widgetProperties` ... appended to the end of the designer's property table
   * `#widgetPropertiesToIgnore` ... hidden in the designer's property table
   * `#widgetClassIcon` ... icon in the designer's widget tree
   * `#widgetClassName` ... text in the designer's widget tree