CapeSoft.Com
Clarion Accessories
Draw
Documentation
DrawHeader
Download Latest Version Index History Template Class
CapeSoft Logo

CapeSoft DrawHeader
Documentation

Installed Version Latest Version

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.

Draw headings WOW

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

Draw header example

Template Reference

Global Extension

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.

Text Tab

Heading
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.)
Override With
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.
Text Shadow
If the Auto-Text Shadow is off, then enter your preferred shadow values here.
Shadow Color
The color of the shadow. Usually either a pale grey, or a pale version of the font color.

Icons Tab

Auto-Icons
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.
Icon Size
The size of the icon to use in pixels - defaults to 32.
Icon
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.

Background Tab

Background Color
The background color for the header.
Bar Color
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.
Bar Height
The height of the bar, in Pixels.
Background Shading
The Shading style to use for the background.

Advanced Tab

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 ThisWindow.INIT method to the ThisWindow.ASK method.

Auto Local Extension

A second Global Extension exists called Activate Auto Headers. If this is added globally then the Draw Auto Header extension template is added to all the procedures in the app. This is a fast approach to adding all the local extensions if you want them on all the windows (at runtime).

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 class:
For the class methods and properties please see the Class Reference.

Examples

There is an example of the Dynamic header in the \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.

Draw header example

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.

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

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 application,

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 \Clarion\Accessory\Libsrc\Win folder if you want to use them across multiple systems.

MyDrawHeader.Inc

   include('DrawHeader.inc'),ONCE

myDrawHeader Class(DrawHeader),Type,Module('myDrawHeader.clw'), |
                   Link('myDrawHeader.clw',DrawLinkMode),DLL(DrawDLLMode)
OverrideSettings Procedure (), Derived
              End

MyDrawHeader.Clw

   Member()
  Include('Equates.CLW'),ONCE
  Include('Keycodes.CLW'),ONCE
  Include('Errors.CLW'),ONCE
  Map
    include('DrawAPI.clw'), once
  End ! map
  Include('myDrawHeader.inc'),ONCE

!-----------------------------------------
myDrawHeader.OverrideSettings Procedure()
  code
  parent.OverrideSettings()
  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 this;
  1. Go to the Draw Global Extension
  2. Go to the Classes Tab
  3. Add your new INC file (myDrawHeader.Inc in the above example) to the Additional INC Files list.

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 by
  1. Go to the Draw Global Extension
  2. Go to the Header / Advanced tab.
  3. In the SetClassName field set the name to use. This setting does not have quotes. For example;
    myDrawHeader
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).

DrawHeader Methods
ChangeIcon Change the icon being used by the control at runtime.
Decide Allows the drawing to be disabled completely.
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 template
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 it.

Class Methods

ChangeIcon

ChangeIcon (string iconName)

Description

Changes the icon being used for the header at runtime.

Parameters
Parameter Description
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: '~MyIcon.ico'
Returns

None

Decide

Decide()

Description

Allows the object to be disabled at runtime. This method has to be used before the call to the Init(pControl) method.

Returns

True if the control should be drawn, false to disable the object.

Display

Display ()

Description

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().

Init

Init (ulong pControl)

Description

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() method.

Parameters
Parameter Description
pControl The Use Equate of the Image control on the window that the class will use to draw into.

Kill

Kill ()

Description

Cleans up the control and all allocated resources.

OverrideSettings

OverrideSettings ()

Description

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.

See Also

Advanced: Creating a Custom DrawHeader class

Resize

Resize ()

Description

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.

SetTextY

SetTextY()

Description

Calculates the height, in pixels, of the header text.

This method id called internally when needed.
 

SetWindow

SetWindow()

Description

Applies the Draw Header to the window, without an existing Image control on the window.
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 0.
 

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
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 - Shades from bgColor to bgColorEnd.
Draw:SingleShade - Shades from bgColor to bgColorEnd with a highlight as specified by the .highlightPos property.
Draw:DoubleShade  - 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
Draw:Vertical
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 the 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.