FireMonkey ListBox With In Place Editing

I’ll admit to having a personal bias against modal dialog boxes. They interrupt my workflow and thought process. So, I rather like the way Windows Explorer works when editing a filename - the text changes to an edit box and I can type in the new filename, or simply hit escape and move on.

I saw no reason why I shouldn’t be able to do the same thing in FireMonkey. A FireMonkey list box is simply a container for other controls, so I reasoned I could simply replace the existing text control with an edit control when the user began an edit, and swap back to the text control when the edit was finished. We’ll start editing when the user hits F2, finish on pressing the enter key and let users back out by hitting escape.

Here’s a screenshot of what I came up with:

EditListBoxItem

A listbox is a container for other controls, but only children of TListBoxItem will actually show up within the list, so first we need to create such a child, we’ll call it TEditListBoxItem:

EditControl is the control which will do the editing. I could have explicitly made this a TEdit, but if we use a TSyledControl then users of our code can substitute any suitable control. They could use some kind of date or filtered editor, or one with validation. Or they could use something completely unrelated to text and text editing.

We’re relying on the creator of the list box item to create and assign the edit control. When they do we need to do some setting of properties, as shown above. We need to monitor the OnKeyDown event so we can intercept the Enter and Escape keys to finish editing.

Because we don’t know that our edit control will be an edit box we can’t simply read and write the Text property. Fortunately FireMonkey gives us a more generic way of getting and setting content using the Data property. This is a Variant and can read or write any data type as used by the control.

Note in the SetEditControl method above that we took care to preserve the value of any control already in existence by getting the old Data and assigning it to the new Control.

And refer back to the class definition above to see that we override the GetData and SetData methods to get and set data. We also add our own Text property since GetText and SetText aren’t virtual. Our GetText and SetText simply pass values to and from the edit controls Data property. It’s a bit redundant in our usage, but adding this functionality should help prevent obscure errors somewhere down the line.

TInPlaceEditListBox

Now we can move on to the list box itself:

We’ll start in the overridden KeyDown method, which simply monitors for the F2 key:

Here we,
* Check we have a valid ItemIndex.
* Stop any exising edits.
* Preserve the scollbar value so we can restore it later.
* EditUpdate is used to prevent some icky side effects (see below).
* We free any existing EditItem (our TEditListBoxItem), create a new one and call CreateEditControl to instantiate the control to go inside it.
* We preserve the existing ListBoxItem into EditedItem, so we can restore it once editing is complete.

Now we need to get our TEditListBoxItem (EditItem) into the list. TListBox has an InsertObject method to insert an item anywhere in the list. Unfortunately a bug in FireMonkey (as of XE2 update 4) means this always fails with an exception. The workaround for this is to call AddObject which adds the item to the end of the list (and is a synonym for setting the Parent property), and then call Exchange with the two items we want to swap.

EditItem (Our new item) is now in the correct place in the list, and EditedItem (the old text item) is now at the end. We can simply null EditedItems Parent property to remove it from the list.

Next comes a line lifted from the dark side, and one I’m not proud of. Recall our discussion on setting a generic data value through the Data property? What I should have been able to write here is

But the FireMonkey designers borxed things up in TListBoxItem by adding a fresh Data property of type TObject which, as far as I can see, isn’t actually used anywhere in FireMonkey.

The workaround is to explicitly call the inherited GetData and SetData methods which aren’t overridden in TListBoxItem, but they are hidden because they’re protected and out of scope. We can bring them into scope by creating a do nothing descendant of TListBoxItem (

) in our unit and use some typecasting as shown above to get to the methods. Like I say, nasty but necessary.

After that we can return to sunnier climes. We:
* Give the edit control focus.
* Select the new item, to restore the list boxes ItemIndex property.
* Restore the scrollbar to where it was.
* Animate the opacity property for a pretty effect.

Tidying up

To handle when the user finishes editing we use the EVKeyDown event handler which monitors for Escape and Enter keys and calls EndInPlaceEdit, which is pretty much a reversed copy of InPlaceEdit: swapping out our editor for whatever was there before and saving (or not) the Data.

There’s only a couple more things of note.

We override the SetItemIndex method to stop editing if another item is selected (e.g. by a mouse click). Here’s where our EditUpdate field comes in useful: all that inserting and moving list items around plays havoc with the ItemIndex property and we need to protect against accidentally finishing editing before we’ve even started.

In EVKeyDown we add code to move the editor when the user keys up or down:

but we double check ItemIndex can be changed. Otherwise moving up from the first item or down from the last would cause the editor to be recreated and look nasty.

Finally we’ll look at CreateEditControl which lets developers use their own edit control, or defaults to a TEdit:

Back to the list box item

Before I leave you in peace I’ve got something else to show you. Look at the constructor of TEditListBoxItem:

We’re setting the CanClip property to false. This means that the item and it’s children can show outside the bounds of it’s owner (the list box). The first effect of this is that the editors glow effect can show outside the list box. IMHO this simply looks better.

The second and potentially more exciting effect is that the editor itself can appear outside the listbox. Imagine the list box contained some potentially long strings but you don’t want a wide form. The user can now have a compact display but with a nice long edit box when necessary.

The code to achieve this is simple, in the list items SetEditControl method simply comment out the line that sets the Align property and set a reasonable width for the edit control:

Download the full source:

Enjoy, Mike.

Full Source

Filed under Coding on 17th April 2012 by Mike Sutton. Permalink Comments (0)

Triggering Effects and Animations in FireMonkey Components

If you’ve used FireMonkey styles, you’ve probably got used to using triggers to initiate animations and effects. I.e. setting a TColorAnamation when IsMouseOver = True and triggering a TGlowEffect when IsFocused = True. But if you’re creating your own components, how do you create triggers which you and others can use to style your component? That’s what we’re going to look at today.

Below is a form with two TEdit controls. I’ve coded them to show basic password validation. The first box shows a red background if the password is not secure enough (less that six characters here), the second shows a TInnerGlowEffect under the same conditions. Both boxes show clear when the password is adequate (see the second screenshot).

TValidateEdit

I started by subclassing TEdit as follows to create a generic edit box with validation. Validation is done by calling the OnValidate event:

The first thing to notice is our trigger property, IsInvalid. As with the triggers you’ve already seen it starts with ‘Is’. This is not a requirement, but it is a convention, and one you would do well to keep to, just like you start your types with a T. Following the convention means that you and others will instantly know which propetries can be used as triggers. This is important since controls with trigger properties have special code to enable the property to be used as a trigger. Other than the naming convention there is nothing special about the declaration of trigger properties.

Now, lets take a run through the code and see how things work. First up is our overridden KeyDown method.

All we do here is call DoIsValid to check whether the new content is valid.

We need to override ApplyStyle and call DoIsValid so that IsInvalid will be set properly at startup and if the style is ever reloaded. In our case this means that when the password editor is created, and therefore empty, it will show as invalid.

And finally on to the meat of our code, DoIsValid. First we call the onIsValidate event handler and set FIsInvalid. All bog standard stuff.

Following that are the two lines which do the work:

These are two standard methods of TFMXObject (a parent of all FireMonkey objects). StartTriggerAnimation starts any appropriate animations. ApplyTriggerEffect shows or hides any appropriate effects.

Both methods look through the child objects for effects and animations to trigger. These can be animations and effects in the control’s style, or those added directly to the control either at deisgn time or run time.

The first parameter is AInstance (of type TFMXObject). This is the object which contains the trigger property. Here we’re passing Self, but you could just as easily pass in another control with a trigger property. For example you could change a property of another control, and then trigger an animation in your own style based on that controls state.

Finally we have the trigger property itself. This takes the name of a property as a string. The property must be a boolean. Refer to the discussion above about naming conventions, but also keep in mind the previous paragraph: you could start an animation based on any boolean property on any object. But if you do this, note that the animation will not get updated when that property is changed unless you explicitly do it yourself. Caveat emptor.

Styling

Here is the style using animations, a straight copy of the EditStyle to which I added two animations, one to initiate the animation, the second to clear it:

And the properties for the first animation:

Here we have the StartValue and StopValue and the Trigger (IsInvalid=True). The second animation is simply the reverse. Note however that we also have StartFromCurrent=True. If this is not set then each time we call the StartTriggerAnimation function the animation will change to the StartValue and animate to the StopValue. In our case that means that each time we type a character the background would turn white, then fade to red. Not what we want. Starting from the current value stops this (It starts at red and stays there).

Prior to XE2 Update 4 I noticed a bug with this behaviour. Under some circumstances the animation would switch immediately to the StopValue, rather than animating. To get around this I changed DoIsValid so that the animations would only run if the trigger property had actually changed:

Now that this is fixed with Update 4, you have a choice of using either technique.

Styling for effects

Here is the style for the version which uses an effect, with the newly added TInnerGlowEffect highlighted:

The only thing to note here is that the effect must be added as a child of the object in which we want the effect to appear, the background rectangle here. I first created this code under XE2 Update 3 and added the effect as a child of the main TLayout and it worked fine. This no longer applied under Update 4: hence it’s current placement.

Round up

And that’s all there is to it. Just remember that you can be incredibly creative with FireMonkey styles. Instead of changing the background of the TEdit I could have added an image and had it change from a cross to a tick. I could have added some text (‘Password too short’) either below or beside the edit box and changed it’s opacity. The beauty with FireMonkey is that once I’ve added the trigger property you (or your designer) are free to be really creative with how that trigger affects the styling.

Download sources

Full source of ValidateEdit unit:

s opacity. The beauty with FireMonkey is that once I

Filed under Coding, Styles on 25th March 2012 by Mike Sutton. Permalink Comments (0)

FireMonkey Grids: Basics, Custom Cells and Columns

MonkeyStyler uses a couple of heavily customised grid columns. I spent some of last week finishing off the styling for them. The whole process has taught me a lot about FireMonkey grids. Prompted by this question on StackOverflow I though now would be a good time to share some of what I have learnt.

So, in this post I’m going to cover the following:

• How FireMonkey grids work;
• How to create a custom cell class;
• How to create a custom column class;

Our StackOverflow poster wanted to know how to set the alignment and color of a grid cell, so I’ll concentrate on those issues in this post. We’ll create an app which has a grid showing two columns. The first will display the row index, the second financial figures, which are right aligned and with a background which changes to red when the figure is negative. I’ll cover most of that today with the styling issues in a future post.

FireMonkey Grids

Grids in FireMonkey are much more flexible than those in the VCL. But, of course with flexibility comes complexity. Fortunately, once you’ve learnt a few basics the rest comes fairly easy.

A FireMonkey TGrid is simply a container, adapted to contain children of type TColumn. A column is simply a container for a series of cells. We’ll get to the cells later.

To start with we’ll create an app which contains a TGrid. In the Delphi form designer, right click on the empty grid and select the Element Editor. Here, add a TColumn and back out. This will be a basic column in which we’ll display the row index.

On to the code, here’s the interface:

Data is a list which we populate with random values in PopulateData.

FormCreate sets up our Data values, and also creates and adds another TColumn to the grid. We’ll create this in code so it’s easier to play around with. Note that, as always in FireMonkey, we simply assign it’s Parent property to the grid to assign it to the appropriate container.

Go back to the form editor and create a method for the grids OnGetValue event:

What happens here? The TColumn has a number of cells to display data but it only creates as many cells as it has visible rows. I.e. if a grid has a RowCount of 100, but only 20 cells are visible then only 20 cells are created. Whenever you scroll the grid each cell gets recycled. Because of this a grid cell cannot store any data between refreshes. (Or, more accurately, it should not store data because if it does it will be displaying the wrong data).

So, every time a cell is displayed the grid calls the OnGetValue event for that cell. OnGetValue passes the column and row indexes for the cell (the virtual column and row indexes) and our event handler needs to return the value to display in the Value variant parameter.

Run the above and you’ll see something like:

(Aside: the grid appears to have a few display issues if you don’t show headers, hence why I’ve kept the headers here).

Custom Columns

Ignoring the rounding issues (we’re using Singles for simplicity here), you can see that the column of supposedly financial figures really needs to be right aligned (we’ll come to rounding and formating later).

We’re using a TColumn for the figures, which is a container for TTextCell. The definition for TTextCell is:

So, it’s just an edit control with the parent set to the column. Haha. Easy. To get our control right aligned we just need to set the TEdit’s TextAlign property, which we can assign when the cell is created.

Each cell is created in the columns CreateCellControl virtual method. Look for the method in TColumn and we see:

So, we’ll create our own custom column and override the CreateCellControl to do our work for us:

Update the FormCreate to create TFinancialColumn and we see:

Custom Cells

But we’ve now taken things as far as they can go with the built in TTextCell. It’s time to create our own cell class so we can really get things looking how we want.

Look again at the definition of TColumn.CreateCellControl. Note that it returns an object descending from TStyledControl. A TStyledControl is the parent of any control which can have styling applied. In other words, any visual control in FireMonkey. FireMonkey already does that with TCheckCell, TProgressCell and TImageCell for check boxes, progress bars and images.

And you can extend this to create custom cells using any control you like. You could go really freaky and use a list box or tree view within a cell. You probably wouldn’t want to, but FireMonkey is flexible enough to do it if you want. And all FireMonkey controls can own - be containers for - other controls. So you can create a cell which is made up of multiple controls.

Take a look at the property editor grid for MonkeyStyler in the screenshot below from the the preview images blog post and you’ll see that the values column contains:

• A TColorBox for color previews (the Fill.Color property);
• A TEdit (editable properties);
• A TCheckBox (boolean properties);
• A TButton (for the animation menu button and image)

with code to set each item’s Visible property depending on the data type.

TFinancialCell

But, enough showing off, lets get back to our financial column. The TTextCell is just a TEdit. Not much customisation we can do there. What we’ll do is create our cell as a TStyledControl which will contain an alClient aligned TEdit.

Now, look at the SetData method, which is the Setter for the Data property. Data is defined in TFMXObject, the parent of all FireMonkey objects. Earlier we saw how the grid fetches data for each cell by called the OnGetValue event, well after it’s fetched the data it passes it on to the cell objects Data property. So, we override the SetData method to get the data we need to display.

Before we can run things we need to update the columns CreateCellControl to reflect our new cell class:

Now things are looking much better:

Round up

So, we have a grid column which is formatting the data how we want. This article is already long enough, so I won’t bore you any longer, other than to say that I will return at some future point to show you how you can use styles to format the grid cells we created today.

Enjoy.

GridBasics.zip - Download the project sources.

Full source:

Filed under Coding on 13th February 2012 by Mike Sutton. Permalink Comments (0)

TBitmapSpeedButton: Loading Images from the Style

Recently recently blogged about creating a TBitmapSpeedButton - a button which could show a bitmap image. When I came to use it I realised an ideological flaw. I was using the old VCL style model of loading a bitmap at design time to use in the application.

That works fine for VCL, but in FireMonkey it’s good practice to offload the visuals to the style. What would be ideal is if, in the form designer, I can specify a style resource for the image to be used. Now I, or my visual designer, can choose an image to use without needing access to my source code. If the look of the software needs updating I can just update the style file with new images and the app will look different without having to edit the source code (or at least the FMX file, which as far as I’m concerned is the same thing.

So, I’ve updated my component with two new properties:

TImageType is either itBitmap or itStyleLookup and tells the component where to get the bitmap data from.

The only interesting bit of new code is the new UpdateImage method:

which shows how to find a style resource either from the current stylebook, or if that isn’t found, from the applications default style.

Download updated sources

 

Filed under Coding, Styles on 26th January 2012 by Mike Sutton. Permalink Comments (0)

My First FireMonkey Custom Control: TBitmapSpeedButton

One thing which surprises me about the FireMonkey library is that the TSpeedButton has no option to display an image (indeed, none of the button controls do). Since I’m at the stage where I need such a control for the interface for MonkeyStyler I decided this would be the perfect opportunity to create my first FireMonkey custom control.

So, lets look at what we want: We want to descend from TSpeedButton, so we can easily add the control to a tool bar (actually a FireMonkey toolbar can accept any control, but the styling for a speed button is closest to what I want). We want a bitmap image, and we want the option to have the image to the left, right, top or bottom of the text, or to have the image centered with no text.

I started by creating the style. This gets the basics of styling out of the way for when we create the code to interact with it. Of course, at this stage styling can be quite basic, simply adding the controls we need and setting basic properties.

The Style

Copy the styling for SpeedButtonStyle to a new style file (bitmapspeedbutton.style) from Windows7.style (Note: I did this with a couple of clicks in MonkeyStyler but at the time of writing you’ll have to make do with cutting and pasting from the source files).

Here is the style for a TSpeedButton:

We want to add our image at the highest level below the root TLayout. At this position it can interact with the TText as we adjust it’s position. We could just add the TImage directly, but if we did, adjusting the Align property would change it’s size. And unless we get messy with the padding we would get undesired stretching of the image.

So, what we’ll do is add a TLayout, and add the TImage as a child:

Set the TImage’s properties:

For the parent TLayout:

and for the root TLayout:

.

Save the file, and load it into the StyleBook for your test project (also, point your form’s StyleBook property to the StyleBook).

The code

Start by creating the code for the class:

and add the Create method:

Add some code to your test project to create a TSpeedButton in code:

Run it and you’ll see ... nothing. Okay, so the default style for a speed button is invisible unless you hover over it (perhaps not the best choice for a custom component, but we’re here now, so we’ll have to live with it). Actually you can see it by hovering your mouse over, you’ll just need to be good at finding where we centered it to.

What happened here? If you listen to some descriptions of FireMonkey custom control, they’ll give you lots of code to load a style into a FireMonkey control. But if you read such stuff ignore it. FireMonkey actually does all that stuff for you. If you dig into the FMX.Types unit and look at the source to TStyledControl.GetStyleObject you’ll see (amongst a lot of other stuff):

So, FireMonkey takes the ClassName of you control (TSpeedButton), appends ‘style’ and removes the preceding ‘T’, giving us ‘SpeedButtonstyle’ and automatically loads the appropriately named style (unless you, or your users, set the StyleLookup property, in which case it automatically loads that one instead).

(Aside: TStyledControl is the parent of all controls which can have styling applied).

Functionality

So, we have a control which looks like a TBitmapSpeedButton, we just need to add some code so it behaves like one.

Lets flesh out the interface section:

The first bit of interesting code is the ApplyStyle method:

Most custom controls will need to override this virtual procedure. It is called whenever a style is loaded or modified, and it is here where we need to grab any objects which we will be manipulating, in our case the TImage (image) and it’s parent TLayout (imagelayout) objects.

Go back to our interface section and look at the Bitmap property. A naive implementation might use a getter and setter to fetch/modify the bitmap object contained within the styles TImage object. There’s two problems here: first the style isn’t applied at the time the object is created, but slightly later (I presume on some kind of OnIdle event). So, anyone instantiating your object:

Will at best get ignored, or at worst get an access violation, depending on whether you tested the validity of your FImage field.

The second issue is that if you style ever gets updated the bitmap data saved in the styles TImage will get deleted and you’ll get a new, empty, TImage object.

So, what we need to do is ‘cache’ any data which will be sent to styling objects. In our case, that’s the TextVisible and ImageAlign property data in addition to that for Bitmap.

Look back at the ApplyStyle code above and you’ll see that I’m reloading the Bitmap and TextVisible data and calling UpdateImageLayout which will apply the ImageAlign and a few other features still to be added. Thus if a new style gets loaded the display will be updated to reflect the components state.

But, this code only operates when the style is applied, we also need to update the styles properties when a user sets our properties. So, we also have setters for ImageAlign and TextVisible, e.g.:

(FTextObject is inherited from our TSpeedButton parent (though, oddly, it isn’t declared as a TText, even though the TSpeedButton pretty much ignores it if it isn’t one).

For FBitmap we key into it’s OnChange event, with our EVBitmapChange handler (by convention I prefix event handlers with EV):

Conclusion

So, that wraps up the interesting stuff. I’ve added a few more properties, which you can see in the full source below. And I’ll sum up that I’m rather pleased with what I can achieve in FireMonkey in only 152 lines of code (plus the style).

Links:
Full source zip (.pas and .style files).
Documentation for the completed component.

Debugging tips:
Check you have the style loaded into the forms StyleBook component.
Check that the forms StyleBook property points to the StyleBook component (it’s not set by default).

Enjoy, Mike.

Update: TBitmapSpeedButton: Loading Images from the Style

Full .pas source:

 

Filed under Coding, Styles on 14th January 2012 by Mike Sutton. Permalink Comments (3)