The DrawHeader Dynamic Window Header template and class
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:
The Global Extension contains a tab for the DrawHeader settings.
Use Old DrawHeader 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.
At the local level the heading text is usually either set specifically, or defaults to the Window Caption property.
If you add a value here then this will be used instead of the Window Caption.
Use AnyFont First
Retrieves the Font, and FontSize to use from AnyFont (if it is in the app).
Use Makeover Next
If Anyfont is not in the app, or has not set the font, then use the Makeover setting (if it is in the app.)
If a Font is set here then it overrides the AnyFont and Makeover settings.
Text X Position
The position of the text (horizontally) in the image. If Icons are being used then a value of 75 is recommended.
If Icons are not being used then a value of 20 is recommended.
Auto Text Shadow
If this is on the default (appropriate) values for the text shadow is used.
If the Auto-Text Shadow is off, then enter your preferred shadow values here.
The color of the shadow. Usually either a pale grey, or a pale version of the font color.
If Auto-Icons are on then an icon will be selected automatically, based on the data table being used by the procedure.
For example a Form on the CUSTOMERS table will result in the use of CUSTOMERS.ICO. The icon can also be set locally
for each window.
The size of the icon to use in pixels - defaults to 32.
If an icon value is set here then it will be used on all windows where a local icon is not set. In other words, this
is the default icon that will be used by the windows. If this icon is set then Auto Icons will not be applied.
Icon X Position
The horizontal offset of the Icon in pixels.
Icon Y Position
The vertical offset of the Icon in pixels.
The background color for the header.
The color of the horizontal separator at the bottom of the header.
Shade Bar To
If this is set to something other than COLOR:NONE then the bar will shade from the Bar Color to the Shade color.
The height of the bar, in Pixels.
The Shading style to use for the background.
Set Class Name
This is used to change the class used by all the local procedures. See
Advanced: Creating a Custom DrawHeader class
Init Later, in ASK
This option moves all the initialization code from the
method to the
Local Extension Options
The local extension options are the same as the global extension options.
Where a Radio or Drop option is set to Default
then the global setting is used.
For Colors, if the color is set to Color:None then the global setting is used.
Upgrading from the old DrawHeader template and
procedure from versions 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
- 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
- Automatically uses the correct icon if the height of the control
- 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
There is an example of the Dynamic header in the Clarion\3rdparty\Example\Draw\Headings
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:
Options for old control template (on the actions tab of the control
- 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.
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
- Text - the string to display as the header (if left blank window caption
- 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)
Advanced: Creating a Custom DrawHeader class
The DrawHeader template allows for a lot of customizability with regard to
the Draw header on each window. There may be cases however where you want to
override the behavior of the DrawHeader class to customize it for your
You can override the class by making a Derived Class - in other words one
that sits between the shipping DrawHeader class, and each procedure in your
program. By editing this class you effectively edit the behavior of all the
headers on all the procedures.
Once the Derived Class has been created, it needs to be applied to the
After that the new class is applied to the the procedures. This can be done on the app level (ie set all the procedures in
the app at once) or at the procedure level (so changing the behavior only
for specific procedures.)
Create a Derived Class
A derived class consists of 2 files. An INC file and a CLW file. Here is
an example of a derived class, which overrides the OverrideSettings
method. This could be used to override template settings, but on a
system global level.
These files can be in your application directory (if they are only used
in one system) or they can be placed in the
folder if you want to use them
across multiple systems.
OverrideSettings Procedure (), Derived
End ! map
self.barStartColor = color:lime
self.barEndColor = color:none
self.bgColor = color:green
Apply Derived Class to Application
The additional class now needs to be applied to the application. To do
- Go to the Draw Global Extension
- Go to the Classes Tab
- Add your new INC file (myDrawHeader.Inc
in the above example) to the Additional INC Files
Apply Derived Class to Procedures
Each procedure has the class it uses set when the control is added to the window. You can however set the class globally
- Go to the Draw Global Extension
- Go to the Header / Advanced tab.
- In the SetClassName field set the name to use. This setting does not
have quotes. For example;
On the next compile all the procedure will be changed to use this class. This will override any local class name setting
so if you do start using the class name at the local level, to override the global class, then you must clear this setting.
DrawHeader Class Reference
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 behavior of the Draw methods (although all call the parent method).
|ChangeIcon||Change the icon being used by the control at runtime.|
|Decide||Allows the drawing to be disabled
|Display||Renders the header and displays it|
|Init||Initialize the class and settings.|
|Kill||Deallocates memory and cleans up|
|OverrideSettings||A method to override settings set by the
|Resize||Resizes the header and displays it|
|SetTextY||Calculates the height of the
header text in pixels, and sets the .TextY
property based on that.|
|SetWindow||Creates the Draw Control at
runtime, ad moves all the other controls on the window down to make room for
ChangeIcon (string iconName)
Changes the icon being used for the header at runtime.
|iconName||A string that contains the name of the icon to use. Can
be the name of an icon file on disk, or an internal icon using the standard
Clarion syntax of a tilde to indicate a project resource:
Allows the object to be disabled at runtime. This method has to be
used before the call to the Init(pControl)
True if the control should be drawn,
false to disable the object.
Displays the header using the current settings.
Called automatically when the control is resized, so after calling
Resize() it is not necessary to call
Init (ulong pControl)
Initializes 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()
|pControl||The Use Equate of the Image control on the window that
the class will use to draw into.|
Cleans up the control and all allocated resources.
A method called after the settings have been set by the template, but before
the call to .Display().
Use this method to embed code which overrides template settings.
Advanced: Creating a Custom DrawHeader
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 minimizes 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.
Calculates the height, in pixels, of the header text.
This method id called internally when needed.
Applies the Draw Header to the window, without an existing Image control on
The image control is created and all the current controls on the window are
moved down to make space for it.
This method id called internally when the Init(pControl)
method is called, and pControl is set to
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.
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().|
||Position to display the heading at. The Init() method
sets this to a default value.|
||The position to display the heading text at. The
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.|
long||The size of the "blur" for the drop shadow or glow
around the text. If the autoShadow property is set then the
calculates this based on the font size.|
long||If set the shadow size and offsets are done automatically.|
long ||The number of pixels to offset the shadow
horizontally. If the autoShadow property is set then the
method calculates this based on the font size.|
||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.|
||The color for the drop shadow.|
||The name of the icon to use, can be a resource, or
long||The background color.|
||A second background color for gradients.|
||The type of shading. Can be set to 0 for a solid
color, or one of the following equates:|
- Shades from bgColor to
Draw:SingleShade - Shades from
bgColor to bgColorEnd
with a highlight as specified by the .highlightPos
Draw:DoubleShade - Similar to
SingleShade but the color gradient is perpendicular to the shading
The shading is determined by the shadeType and
||Sets the shading to vertical or horizontal can be set
to one of:|
||The position of a highlight for shading types that
long ||The intensity of the highlight if one is used.|
Ulong||The handle of the icon to draw. The DrawHeader class
will automatically fetch the icon from a resource and allocate this handle.
It can be allocate manually by calling the Draw.GetIconHandle()
load a particular icon either from disk or from a resource.|
||The position to display the icon at horizontally,
from the left hand side of the control.|
long||The position to display the icon at vertically, from
the top of the control|
||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.|
||Color used for the bar along the bottom of the
||End color (for shading) of the bar drawn along the
long ||The height (in pixels) of the bar across the bottom. The
Init() method sets this to 5 pixels by default.|
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