DrawHeader
	Return to the main Draw documentation

Contents

DrawHeader Template Options

Upgrading from versions below 2.63

Examples

DrawHeader Methods

DrawHeader Properties

The DrawHeader Dynamic Window Header template and class

As of Draw 2.63 the DrawHeader template uses a new DrawHeader class. This provides better performance, and has no need of a local procedure.

The Draw Global extension provides the ability to use the old or new DrawHeader, as well as to override the class defaults to creating headings. These settings can also be overridden on the local extension for each DrawHeader control, as needed.

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:

Global Extension Options

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 size
The size of the "blur" for the shadow, in pixels, if Auto Shadow is disabled. The higher the number the softer and more spread out the shadow will be.

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.

Local Extension Options

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 customisable.
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 centred 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.

Examples

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 customised in the template settings.

1) Make sure you have added the Draw Global Extension to your application.

2) 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)

DrawHeader Class Methods and Properties

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
	Display	Renders the header and displays it
	Init	Initialise the class and settings.
	Resize	Resizes the header and displays it
	Kill	Deallocates memory and cleans up

Class Methods

Display ()

Displays the header using the current settings. Called automatically when the control is resized, so after calling Resize() it is not necessary to call Display().

Resize ()

Resizes the control - if the control height has manually been changed or the window is wider than the control's width, then the control is resized and redrawn. By default the control is set to resize horizontally, but not vertically. The control will automatically be set to twice the window width on resize, which minimises the number of times that the control needs to be redrawn to improve performance. The control will not be resized if the window size is reduced.

Init (ulong pControl)

Initialises the control with the default settings and stores the image control handle that will be used to display the header. This calls the parent Draw Init(0 method.

Kill ()

Cleans up the control and all allocated resources.

Class Properties

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

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 centred 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.