logo

code-section

Win32 Property Grid Control

A pure light-weight versatile control for everything

screenshot

The property grid control is a C++ native pure win32 control with an API similar to the native win32 controls API. It is an efficient way to present controls to the user without having to design them manually.


  Lightweight

Using only pure win32, the Property Grid control is guaranteed to be lightweight and responsive even with lots of items.

  Clean API

1 Header file for the traditional win32-style API for interacting with the control (optional C++ wrapper planned), and 1 header for the Item class which enables you to add new control types easily.

  Open-source

You only have to add the source files to your project and you're ready to go! Being open-source and well commented, you can easily make tweaks and customizations to the control, and share new features and bug fixes with other users.

  Easy to Use

With a "Getting Started" tutorial (soon), comprehensive documentation, and well-commented code and samples, it's easy to have the control functioning in your application in no time.

  Versatile

The property grid control can be used as a child window or a popup window. It can be used to edit many kinds of data, and it can be extended easily by deriving from a single well-documented "Item" class.

Sample Code

The following sample code shows how easy it is to add controls (items) to the property grid control in C++.

HPGITEM hCategory = PropertyGrid_InsertCategory( propGrid, 0, TEXT(""), NULL, NULL, NULL );

PropertyGrid_InsertEdit( propGrid, 0, TEXT("Name"), hCategory, NULL, NULL, TEXT("Cube01") );
PropertyGrid_InsertFileName( propGrid, 0, TEXT("Resource File"), hCategory, NULL, 0, NULL );
PropertyGrid_InsertColor( propGrid, 0, TEXT("Selection Color"), hCategory, NULL, NULL, RGB(100,100,250) );

HPGITEM hCol = PropertyGrid_InsertComboBox( propGrid, 0, TEXT("Collision"), hCategory, NULL, NULL );
PGCombo_AddItem( propGrid, hCol, TEXT("None"), 0 );
PGCombo_AddItem( propGrid, hCol, TEXT("Bounding Box"), 1 );
PGCombo_AddItem( propGrid, hCol, TEXT("Per-Triangle"), 2 );
PropertyGrid_SetInt( propGrid, hCol, 0 );

PropertyGrid_InsertCheckbox( propGrid, 0, TEXT("Visible"), NULL, NULL, NULL, NULL, TRUE );
PropertyGrid_InsertCheckbox( propGrid, 0, TEXT(""), NULL, NULL, NULL, TEXT("Active"), TRUE );

PropertyGrid_InsertSlider( propGrid, 0, TEXT("LOD bias"), NULL, NULL, NULL );

HPGITEM hLoc = PropertyGrid_InsertCategory( propGrid, 0, TEXT("Location"), hCategory, NULL, NULL );
PropertyGrid_InsertSpinBoxNumber( propGrid, 0, TEXT("x"), hLoc, NULL, NULL );
PropertyGrid_InsertSpinBoxNumber( propGrid, 0, TEXT("y"), hLoc, NULL, NULL );
PropertyGrid_InsertSpinBoxNumber( propGrid, 0, TEXT("z"), hLoc, NULL, NULL );

Contol Types

The Property Grid, out of the box, supports the following control types:

Control Type Description
Category This is a special non-editable item which is displayed distinctively and is used for grouping items together.
Edit Supports read-only, numeric, and multi-line options.
File-Name Used to allow the user to select a file from the local file system. Can be used as a Save File or Open File selector, with parameters such as file type filters, etc.
Color Button This uses a simple custom control called "ColorBox". It displays a color, and when clicked, opens the system's ChooseColor dialog to allow the user to select a color.
Combo Box The combo box allows the user to select an item from many items from a drop-down list.
Check Box A yes/no control which can have any text representing to the user what the control really represents.
Slider For numeric values when the range is known. There are utility functions that allow the program to get/set the value of a slider using a float from 0.f to 1.f for convenience.
Spin-Box This is used for numerical values. A spin-box item is a pair of an Edit control and a custom control that is used to quickly increase or decrease the value by clicking and dragging. Dragging left or down decreases the value, while dragging up or to the right increases it.
Blank Items These are useful for storing user information and for custom-drawing, where the client can draw an item without having to define a new item type. note: custom drawing functionality is being re-written to be cleaner and easier to use.
Additional Types You can easily add your own custom types simply by deriving from the Item class. Additionally, more control types are planned.
screenshot
The image shows Property Grid controls being used as children of a more complex window to edit the properties of various entities

Current Status

The Property Grid control is still in development. It's free for non-commercial use. To use it commercially, you need to purchase a commercial license.