CapeSoft DrawHeader
Documentation

• Introduction to DrawHeader
• DrawHeader Template Options
• Upgrading from versions below 2.63
• Examples
• DrawHeader Methods
• DrawHeader Properties

The DrawHeader class enables you to quickly add really nice headings to your windows. Once you've added the Draw Global extension to the application, drop on the control template (called DrawHeader - Window Heading) to the window(s) that you require the draw template on, and you're done.

The DrawHeader uses the same coordinate system as the normal Draw control and a Clarion window. The control uses pixels for measurement, not dialog units.



DrawHeader Control can be populated onto your windows to create dynamic headers:

Basic DrawHeader settings

Use Old template Uses the old DrawHeader template, which does not provide the option of modifying the behaviour at the template level and relies on the procedure imported into your application. This is not recommended except for temporary backward compatibility if you have custom code in the old imported procedure. Override default settings Enable this to override the class defaults and use the template to control the settings for the Header controls. These settings are all optional, leave them blank to use the defaults. Heading and Icon Overrides the window heading and icon. Leave these blank to use the Window heading and icon as the defaults. Note: The two entry fields in this section are the only entry fields which require variable names to be prepended with and exclamation mark (!) and do not require quotation marks around string literals. Font Override the font settings, allow the color, font name, size and style to be set. If any setting is left blank or zero, then the default values are used.

DrawHeader Shading settings

Background Color The background color of the control, if Background Shading is enabled then this is the color that shading starts at. Bar Color The color for the bar that runs along the bottom of the control. Bar Height The height of the bar that runs along the bottom of the control, in pixels Background Shading Use this option to shade the background of the control in a variety of manners. The image displayed below this section indicates the style of shading select (but does not reflect the colours selected). Shade Color To Only applies if background shading is enabled, this is the color that will be shaded to from the background color. Shading direction The direction that the shading should run in (top to bottom, or left to right) Highlight position Only applies to Highlight and Double shading, indicates the position of the highlight on the bar. Highlight Intensity Indicates the intensity of the highlight, from 0 (no highlight) to 100 (pure white highlight)

DrawHeader Advanced

Auto text shadow Calculates the shadow size and offset automatically based on the heading size. Horizontal and Vertical offset The offset for the text shadow if Auto Shadow is disabled Shadow color The color of the drop shadow Icon x and y The x and y coordinate to place the icon at on the control Text x The horizontal position of the heading text. The vertical position is automatically calculated to ensure the text is always centered in the control vertically. Class Name Specified the class to use for this object. Use this to override the default class and use a custom class for creating the header.

The local extension is identical to the Global extension, except that in order to use the local settings you need to tick the "Override Global Settings" checkbox. By default the control will use the Global settings.

Upgrading from the old DrawHeader template and procedure from version prior to 2.63

The settings are now all accessible via the Global Draw extension, and can also be overridden using the local extension. By default the new template and class will be used, however the old template (which uses the imported headings procedure) can still be used by ticking the box on the global extension (to use the old template and procedure for all headers), or on the local extension (to use the old template and procedure for a specific header).

Some of the new features of the DrawHeader class:

• The local procedure is no longer required, and does not need to be imported
• Does not create and destroy a Draw object each time the control needs to be drawn
• Full control over the object setting using the DrawHeader object
• More properties exposed at the template level (global template settings coming soon)
• Fast, intelligent built in resizing. Add the SV resizing extension and the control will handle all resizing. No hand coded needed.
• Shade background support,
• No icon control is needed or created, loading icons from disk and resource is handled internally and directly.
• DrawHeader is based on Draw and hence everything supported in Draw is supported in DrawHeader - making it fully customizable.
• Automatic icon size selection based on the control size
• Full backward compatibility - existing controls continue to work and provide upgraded functionality
• New shaded
• Automatic positioning if the height of the control changes (support for vertical resizing)
• Automatically uses the correct icon if the height of the control changes.
• Text is centered in the control based on the font sized used and the height of the bottom bar (if any).

For the class methods and properties please see the Class Reference.

There is an example of the Dynamic header in the Clarion\3rdparty\Example\Draw\Headings directory.

The dynamic header template allows you to easily add a title to a window that dynamically renders a drop shadows title and icon. By default the window title and icon are used, but these can easily be customized in the template settings.

Make sure you have added the Draw Global Extension to your application.
Add the control template to each window you want to use the header on:
• In the window editor choose "Control Template" from the the Populate menu, or use the populate template button in the toolbar.
• Select "Drawer Header - Window Heading" from the Select Control Template dialog box.

Options for old control template (on the actions tab of the control properties)

All the options can be left as default (blank) and the Window title and icon will be used, or you can customise the look and feel as required.

• Text - the string to display as the header (if left blank window caption is used)
• Icon - the icon to display on the left of the header text (if left blank window Icon, if it exists, is used)
• Color - the color for the bar below the header (the default is the blue displayed in the screenshot above)

The DrawHeader class is new in Draw 2.63 and expands the Draw Header features as well as providing an object that allows the header to be easily controlled and modified.

DrawHeader inherits from Draw, and contains all of the properties and methods of the Draw object. This document covers those methods that override the behaviour of the Draw methods (although all call the parent method).

DrawHeader Methods
ChangeIcon	Change the icon being used by the control at runtime.
Display	Renders the header and displays it
Init	Initialize the class and settings.
Resize	Resizes the header and displays it
Kill	Deallocates memory and cleans up

Class Methods

ChangeIcon

Display

Resize

Init

Kill

These properties are used to determine how the heading will be drawn. They can be overridden manually, or by using the template. The values must be set before the call to Display in order to effect the header. The properties can also be changed in the fly and Display() called in order to dynamically update the header.

DrawHeader Properties
displayText	string(2048)
textX	long
textY	long
blurSize	long
autoShadow	long
shadowOffsetX	long
shadowOffsetY	long
shadowColor	long
iconName	string(280)
bgColor	long
bgColorEnd	long
shadeType	long
shadeDirection	long
highlightPos	long
highlightIntensity	long
iconHandle	Ulong
iconX	long
iconY	long
iconSize	long
barStartColor	long
barEndColor	long
barHeight	long
resizePercentage	long

displayText	string(2048)	The actual text to display. By default the Init methods sets this to the Window title. This can be set at any point before a call to Display().
textX	long	Position to display the heading at. The Init() method sets this to a default value.
textY	long	The position to display the heading text at. The Init method sets this based on the height of the control, the size of the font and the size of the bottom bar (of any) to ensure that the text is always centered in the control. This position is in pixels from the top of the control, and represents the baseline (not the top) of the text. The baseline is the line that each letter is placed onto, letter such as p and g drop below the baseline.
blurSize	long	The size of the "blur" for the drop shadow or glow around the text. If the autoShadow property is set then the Display() method calculates this based on the font size.
autoShadow	long	If set the shadow size and offsets are done automatically.
shadowOffsetX	long	The number of pixels to offset the shadow horizontally.  If the autoShadow property is set then the Display() method calculates this based on the font size.
shadowOffsetY	long	The number of pixels to offset the shadow vertically.  If the autoShadow property is set then the Display() method calculates this based on the font size.
shadowColor	long	The color for the drop shadow.
iconName	string(280)	The name of the icon to use, can be a resource, or blank.
bgColor	long	The background color.
bgColorEnd	long	A second background color for gradients.
shadeType	long	The type of shading. Can be set to 0 for a solid color, or one of the following equates: Draw:LinearShade equate(1) - Shades from bgColor to bgColorEnd. Draw:SingleShade equate(2) - Shades from bgColor to bgColorEnd with a highlight as specified by the .highlightPos property. Draw:DoubleShade equate(4) - Similar to SingleShade but the color gradient is perpendicular to the shading direction. The shading is determined by the shadeType and shadeDirection parameters.
shadeDirection	long	Sets the shading to vertical or horizontal can be set to one of: Draw:Horizontal equate(0) Draw:Vertical equate(1)
highlightPos	long	The position of a highlight for shading types that use one.
highlightIntensity	long	The intensity of the highlight if one is used.
iconHandle	Ulong	The handle of the icon to draw. The DrawHeader class will automatically fetch he icon from a resource and allocate this handle. It can be allocate manually by calling the Draw.GetIconHandle() directly to load a particular icon either from disk or from a resource.
iconX	long	The position to display the icon at horizontally, from the left hand side of the control.
iconY	long	The position to display the icon at vertically, from the top of the control
iconSize	long	The default size for the icon, defaults to 48x48 pixels if the control is large enough, otherwise a smaller icon is selected by the Display() method.
barStartColor	long	Color used for the bar along the bottom of the control.
barEndColor	long	End color (for shading) of the bar drawn along the bottom.
barHeight	long	The height (in pixels) of the bar across the bottom. The Init() method sets this to 5 pixels by default.
resizePercentage	long	Allows the resize width of the bar to be adjusted. By default this is 100, which creates a bar twice as wide as the current width of the window, allowing the window size to be increased without having to redraw the bar frequently. Setting this to 0 always draws the bar the same width as the window, and values in between allow a balance between performance and appearance. We don't recommend values above 100, although there is no limit on the value.