The Structure Editor is used to define the contents of a structure data type. It can be used to create a new structure or to modify existing ones. Structures are user defined data types that contain components. A component is a data type of a particular size and at a specified offset in the structure. The following illustrates the editor for a structure data type.
As shown above, the Structure Editor also includes a bit-level view of the structure layout to improve
understanding of bitfield placement when they are present. Note that the byte ordering is
reversed for little-endian data organizations to ensure that a bitfield is always rendered
as a contiguous bit range. If inadequate space is available for a component label,
within the bit view of the component, it will be omitted. However, holding down the Shift-key
while using the mouse wheel on a component will zoom the view in and out
allowing component labels to appear when space permits. The bit view may also be used to make
and reflect single component selections with the table. Within the bit view any padding bits not visible within
the table view as a component will include a small dot in the center of the displayed bit cell.
The Union Editor is very similar to the Structure Editor, but is used to create or modify a union data type. All the components of a Union are at an offset of 0. The following illustrates the editor for a union data type.
A Structure Editor or Union Editor can be launched from the Data Type Manager, the Code Browser, or the Structure or Union Data Type Editors.
The Structure and Union Editors are composed of the following:
- Edit Actions: The icon buttons at the top of the editor are used to modify this structure. Each button has a different edit action associated with it. These allow the user to: apply changes, insert Undefined bytes, reorganize the current components, duplicate components, clear components (changes them to Undefined bytes), delete components, create array components, and unpackage a structure or array component changing it into its component parts.
- Pull Down Menu: The
icon at the top of the editor provides additional editor actions. These are: show the category path of a component's data type, edit a component's data type, edit the fields of a component, apply a cycle group or favorite.
- Component Table: The upper portion of the editor contains a table with the structure's or union's components. Each component (or row) consists of its offset, length, mnemonic, data type, field name, and comment. See the Component Fields section for more about these fields. The data type, field name and comment are editable fields. The data type's category can be determined by showing the data type category. Components can be added, inserted or replaced in the table using Drag and Drop or by applying a Favorite data type. The data type for a component can also be changed by cycling the data type.
- Structure Information Area: This is the area below the component table with the name, description, category, size and alignment of the structure or union. The structure or union being edited can be renamed from here. Its description can be specified here. Also, it can be changed between unaligned and aligned.
- Immediately below the structure information area is a status line where status messages will appear.
Select the Apply Changes icon
in the toolbar to apply the changes from the editor back to the program or archive.
If editor changes to a structure or union are applied and it is assigned to data in the program, all data items with the structure or union as the data type now have the new data type. In other words, the size or composition of those data items in the program will have changed due to the apply.
Select the Close dockable component icon
in the toolbar to exit from the editor. If you have unsaved changes to your data type, a dialog will ask if you want to save the changes.
To search for text in any column on any row in the editor, enter the text into the Search field and press return to search forward from the currently selected table row. Alternatively, the down
and up
arrows next to the search field can be used to search forwards and backwards respectively. Searches are not case sensitive.
To change the name of the structure or union being edited, edit the Name field in the bottom of the editor. If the name is valid, the structure's or union's name will change when the edits are applied by pressing the editor's Apply Changes icon
in the toolbar.
To change the description of the structure or union being edited, edit the Description field in the bottom of the editor. The structure's or union's description will take effect when the edits are applied by pressing the editor's Apply Changes icon
in the toolbar.
To change the size of the structure being edited, edit the Size field in the bottom of the editor and press the Enter key to apply the new size to the structure. If you are reducing the size of the structure, you will be prompted to determine that you really want to truncate the structure.
At the bottom of the editor is an Alignment field, which indicates how the structure or union being edited will be aligned within other data types. All unaligned structures and unions will have an alignment of 1 (byte aligned) and will therefore not be aligned within other data types. For aligned structures and unions the alignment value is determined based on the alignments of the individual components they contain, whether they are packed internally and whether they have a minimum alignment specified.
In the lower right corner of the editor is an Align check box. When the box is checked the structure or union is aligned. Click the checkbox to change between aligned and unaligned. When a structure or union is aligned, additional choices will appear that allow minimum alignment and packing to be specified.
Unaligned Structures
When a structure is unaligned, with the exception of bitfields, each component shown within the editor immediately follows the one before it. In other words, no automatic alignment or padding occurs. Unaligned structures may be used to position components with known data types at specific offsets within a structure. Therefore, when editing an unaligned structure, the structure editor attempts to prevent defined components from moving to a different offset when performing operations like drag and drop which may consume undefined bytes.
Aligned Structures
An aligned structure is defined similar to a structure in a C header file. The data types are specified for each of the components, but their offsets will be automatically adjusted to the correct alignment based on the data type and position in the structure. A default "undefined" byte cannot be added to an aligned structure, although an "undefined1" component can be and is treated like any other fixed-length datatype. The overall size of the structure is determined by the components it contains and the specified pack value. The alignment and packing behavior is determined by the effective data organization as defined by each compiler specification (data type archives utilize a default data organization). When you select the Align checkbox, the GUI displays buttons to allow an align attribute, align( minimum ), to be specified. It also allows a pack value, pack ( maximum ), to be specified. The following image shows these GUI components for aligning the data type being edited.
align( minimum )
This indicates the minimum alignment to be used when aligning this data type inside another data type. Setting this to a value other than none forces this structure to be aligned within other structures at an offset that is a multiple of the specified value. Specifying a minimum alignment also causes the end of the structure to be padded so its size is a multiple of the minimum alignment.
- none - Sets this data type to have no specified minimum alignment when aligning this data type inside another data type. Align this data type based only on its components and their minimum alignments and packing.
- machine - Sets this data type to have a minimum alignment that is a multiple of the machine alignment when aligning this data type inside another data type. In this case machine alignment means the largest alignment which is ever used for any data type on the program's intended machine.
- by value - The bottom button with a text field next to it allows you to specify a minimum alignment value. This sets this data type to have a minimum alignment that is a multiple of the specified value when aligning this data type inside another data type.
The equivalent of having no C code align attribute on the structure or union is to choose none. The equivalent for a C code attribute of align() without a value is to choose machine alignment. The equivalent of align(4) is to specify a value of 4.
pack( maximum )
This indicates a packing value to be used when aligning the components within this data type. Setting this to a value other than none forces each component of this structure to be packed so that its maximum alignment within the structure is no more than the pack value. However, a component will not be packed if the data type or one of its subcomponents data types has a minimum alignment value specified that exceeds the pack value. Packing also affects the padding at the end of this structure so that the overall size of the structure is the smallest possible multiple of the pack value. If the minimum alignment is greater than the pack value, the end of the structure or union is padded based on the minimum alignment instead.
- none - The components within this structure should align themselves in the default way for the compiler. The components are not being packed with a reduced alignment.
- by value - The bottom button with a text field next to it allows you to specify a pack value. The specified value indicates the maximum alignment to use when packing any component.
The placement of bitfields may be influenced based upon the specified pack value.
The equivalent of having no C #pragma pack attribute on the structure or union is to choose none. The equivalent for a C code attribute of #pragma pack() without a value is to specify a pack value of 1. The equivalent of # pragma pack(4) is to specify a pack value of 4.
Unaligned Unions
When a union is unaligned, the union is the size of its largest component. There is no alignment padding and the alignment is 1 when putting an unaligned union into other data types.
![]()
Aligned Unions
In an aligned union the overall size is at least the size of the largest component, but will be padded based on the alignment and packing. The minimum alignment is specified just as within a structure and affects the alignment in the same way. The pack value is specified in the same manner as within a structure, but only affects the padding in the overall size of the union. All elements in a union have an offset of zero, so the pack value doesn't affect the component offsets. If both a minimum alignment and pack value are specified, the minimum alignment will override the pack value if it is larger.
![]()
A structure and union may define bitfield components which attempt to model bitfield definitions found within C/C++. Unlike other byte-oriented components, bitfield components have the following characteristics:
- A bitfield datatype may not exist anywhere other than within a structure or union.
- A bitfield datatype may not be selected via the datatype chooser or tree since it requires the specification of additional attributes (e.g., bit-size, bit-offset). The bit-size is generally appended to the base-datatype for datatype specification and presentation purposes (e.g., char:1).
- A zero-length bitfield may be defined within a byte but its' precise bit position is controlled by endianess alone. A zero-length bitfield has no affect within an unaligned structure and is intended for use within aligned structures where it may impart alignment affects based upon compiler conventions.
- Inserting a bitfield within an unaligned structure may cause component shifts based upon the specified offset and allocation unit byte size when a placement conflict occurs.
- The start/end byte offsets may be shared with adjacent bitfield components.
- Unoccupied bits within a partially occupied byte are not represented by any component (similar to padding bytes within aligned structures).
- A separate Bitfield Editor, for use with unaligned structures only, must be used to precisely place a bitfield component. Adding a bitfield component via the structure table view via datatype text entry (e.g., char:1) provides only rough placement for unaligned structures since additional bytes will be introduced. The BitField Editor may be displayed using the the Add Bitfield and Edit Bitfield popup menu actions on a selected structure component. The datatype text entry approach must be used for all unions and aligned structures.
While packing of bitfields within aligned
structures is controlled by the compiler specification (e.g., data organization), bit-packing
order is currently fixed based upon endianess. Little-endian packs starting with bit-0 (lsb)
while big-endian packs starting with bit-7 (msb).
The use of bitfield components is not
currently reflected in decompiler results or assembly markup.
A structure may be defined with a trailing flexible array component which corresponds to an unsized array (e.g., char[0]). Such a component, if it exists, is always displayed as the last row within the structure editor with the open edit row for additional components located directly above it. The DataType column for a flexible array always shows the base type of the unsized array which can be modified similar to other components. A flexible array is added to the end of a structure by adding a last row specified by the base DataType (e.g. char) then invoking the array action and specifying an element count of 0. Attempting to specify an element count of 0 is only permitted on the last component row when a flexible array component does not already exist. The presence of a flexible array component does not affect the size of a structure and will not appear within the structure when applied to Data within memory as it corresponds to the memory location which immediately follows the end of the structure.
The use of flexible array components is not
currently reflected in decompiler results or listing reference markup. Its primary purpose
if to reflect the C/C++ source definition of a structure with correct alignment and structure sizing.
While C/C++ support flexible arrays anywhere
within a structure, Ghidra only supports the case where it is the last structure component.
The edit actions are available both from the icon buttons in the editor and from the popup menu for the component table. To display the popup menu, right mouse click on the component table. There are also short-cut keys associated with each of the edit actions.
Insert Undefined Byte
Undefined Bytes can only be inserted into a structure that is not aligned. A single Undefined byte is inserted before the current selection by clicking the
Insert Undefined Byte button.
Move Up
A contiguous group of components can be moved up or down in the structure. Select a block of one or more components. Each time the
Move Up button is pressed, the group of components is moved up one row. In other words, the component that was immediately above the group is now below it. This can be done until the group of selected components is at the beginning of the structure (offset 0).
Move Down
Select a block of one or more components. Press the
Move Down button to move the group of selected components down one row. The component that immediately followed them is now before them. The selected components can be moved down until they are at the end of the structure.
Duplicate Component
To duplicate a component within a structure or union:
- Select the component.
- Press the
Duplicate Component button.
- A single copy of the component is created immediately following the selected one.
If the structure is not aligned, then there must be enough Undefined bytes following the component to accommodate the duplicate. In an unaligned structure, Undefined bytes get replaced by the new copy of the component.
Duplicate Multiple of Component...
To create multiple copies of a component:
- Enter a valid number of duplicates and press the Enter key or the OK button.
- The specified number of copies of the component are created immediately after the selected one.
Delete Component(s)
One or more components can be deleted from a structure or union. Deleting components in a structure will cause the components that come after those being deleted to shift to new offsets.
To delete components:
- Select one or more components to delete.
- Press the
Delete Component(s) button.
- The components are removed from the structure or union.
Clear Component(s)
Clearing a component changes it into Undefined byte components that take up the same amount of space as the component being cleared. Components can be cleared in unaligned structures, but not in unions or aligned structures. This is because the resulting Undefined bytes are not valid components in a union or aligned structure.
To clear components in a structure:
- Select one or more components in the table.
- Press the
Clear Component(s) button.
- Each selected component is replaced by Undefined Bytes. The number of Undefined Bytes will be equal to the length of the component being cleared.
Clearing a component will also erase its Field Name and Comment.
Create Array
To create an array from a single selected component:
- Specify the number of elements. For an unaligned structure, the maximum size of the array is limited by the number of Undefined bytes following the selected component.
- Press the OK button.
- The selected component becomes an array of that same data type with the specified dimensions.
In a structure, an array can be created from a selection of multiple components. The data type of the first component in the selection will be used for the data type in the array.
To create an array from a selection of multiple components in a structure:
- Select multiple contiguous components.
- Press the
Create Array button.
- An array is created. The data type of the first component in the selection is used as the data type of the array. The array's dimension is determined by how many of that data type will fit in the space that was occupied by the selection. The size of the array will be the array that can fit in the selected number of bytes. Any left over (unused) bytes at the end of the selection will become Undefined bytes.
Create Flexible Array
To create an unsized flexible array as the last structure component (assuming one is not already defined):
- Add a component whose DataType corresponds to the base type of the unsized array.
- Select this last structure component in the table.
- Press the
Create Array button or the '[' action key binding.
- A dialog pops up to request the number of elements in the array. Specify 0 as the number of elements in the popup dialog and click OK.
Unpackage Component
Unpackaging takes a single component and replaces it with its own component parts. When editing a structure, array and structure components can be unpackaged by selecting that component and clicking the
Unpackage Component button. For example, the array component Word[4] would become four Word components. If the structure struct_1 was composed of a Float and a DWord, then unpackaging it would replace the struct_1 component with a Float component and a DWord component.
Create Structure From Selection
Creating a structure from a selection takes a contiguous selection of components in the structure editor and creates a new structure from those components. It then replaces the selection with a single component whose data type is the new structure. The components that were in the selection will become the components that make up the new structure. The user does this by selecting the components in the editor and clicking the
Create Structure From Selection button. The user is then prompted for the name of the new structure. Once a unique name is specified the new structure is created and a component containing it replaces the selected components.
The following bitfield actions are available when modifying unaligned structures only and are available via the popup menu based upon a selected component or table row. When working with unions and aligned structures, bitfields may only be specified via datatype text entry specification within the table view (e.g., char:1).
Add Bitfield
With a structure row selected in the vicinity of the desire bitfield placement, the popup menu action (right mouse-click) Add Bitfield may be selected to launch the Bitfield Editor for a new bitfield.
A direct text entry of a bitfield datatype may be specified within the table datatype column (e.g., char:1), although it will always be placed at a default offset.
Edit Bitfield
With a defined bitfield component row selected, the popup menu action (right mouse-click) Edit Bitfield may be selected to launch the Bitfield Editor.
Component Fields
Each row displays information about a component in this structure or union. The DataType, Name, and Comment fields are editable.
The following summarizes the information about each field for a component.
Offset - The byte offset of this component from the beginning of the structure. For unions the byte offset of all components is zero, and therefore this field isn't shown.
Length - The length of this component in bytes.
Mnemonic - The mnemonic (brief identifier) for this component's data type.
DataType - The data type of this component. This field is editable.
Name - The field name associated with this component in the structure or union. When specified, the field names must be unique for the components in a structure or union. This field is editable, except on components that are Undefined bytes.
Comment - A comment associated with this component. This field is editable, except on components that are Undefined bytes.
To rearrange the order of the component fields position the cursor over the header for the table column. Left mouse click and drag the column left or right to its new position.
Editing Component Fields
The DataType, Name and Comment fields are editable. However, the Name and Comment are not editable when the component's DataType is an Undefined byte.
To place an editable field into edit mode:
- Double click on an editable field.
or
- Select a single component row and press F2 to begin edit mode. This puts the first editable field in that component row into edit mode. Tab will then move to the next editable field.
Applying an Edit
In the editable field, pressing Enter applies the value to the field if it is valid and ends the edit session. If the field's value is invalid, a message is written to the editor's status line and the field remains in edit mode.
Canceling an Edit
In the editable field, pressing Escape cancels the edit session without applying the changes to that field.
Editing More Than One Component Field
You can move directly from editing the component 's name or comment field to editing another by pressing Tab, Shift-Tab, UpArrow or DownArrow. The key press only moves the edit session if the current field edit can be applied. Otherwise, an error is displayed in the status line.
Tab
Pressing Tab applies the current edit and moves to the next editable field in the table. If the current field is the last editable one in this component then it moves to the first editable field in the next component. This key moves the edit session left to right and top to bottom in the table.
Shift-Tab
Pressing Shift-Tab applies the current edit and moves to the previous editable field in the table. If the current field is the first editable one in this component then it moves to the last editable field in the previous component. This key moves the edit session right to left and bottom to top in the table.
Up-Arrow
Pressing the UpArrow key applies the current edit and moves to the same field of the previous component in the table if that field is editable. This key moves the edit session bottom to top in the table.
Down-Arrow
Pressing the DownArrow key applies the current edit and moves to the same field of the next component in the table if that field is editable. This key moves the edit session top to bottom in the table.
Editing the DataType Field
This can be any data type that is available in the data type manager. To edit the data type double-click the data type cell. This will show the Data Type Selection Dialog, which allows you to easily enter a data type. It can also be Undefined, a pointer to a data type, or an array.
Basic Data Type
This can be a built-in data type (Byte, Word, etc.), a structure, a union, or a typedef.
For example, Word.
Pointer Data Type
This can be the basic Pointer data type or a pointer to a data type. A pointer to a data type is indicated by following the data type with an *.
For example, Word * is a pointer to a Word.
Array
This can be a multidimensional array of any data type.
For example, DWord[2][4] is an array with 2 elements, where each element is an array with 4 elements that are DWords.
Array of Pointers
Arrays of pointers can also be specified.
For example, Float*[5] is an array with five elements where each element is a pointer to a Float.
Effect of Changing a Component's Size
An unaligned union's size will always be the size of its largest component. If you change a data type for a component and the component size changes, the union size will change if necessary. An aligned union is padded to make its size a multiple of the union's alignment.
How a structure is affected by changing a component's data type depends on whether the structure size is aligned or unaligned.
Unaligned - If the structure is unaligned, then the new component must be less than or equal to the original component's size plus any Undefined byte components that immediately follow it in the structure. In an unaligned structure, decreasing the component size will create Undefined byte components following it to maintain the structure size. Increasing the component size replaces Undefined bytes immediately following the component. The last component of a structure can be always be changed which can cause the structure to grow larger.
Aligned - If the structure is aligned, the component can change size, which affects the structure's overall size and the alignment of individual components that follow it.
Editing the Name Field
When specified, a field name must be unique for the components in a structure or union. It cannot contain blanks.
Editing the Comment Field
The comment can be any Ascii text.
Pointers
Pressing the 'p' key invokes the pointer action on a component. This will generally create a default pointer unless the existing data is already a pointer in which case that pointer will be wrapped with an additional pointer (e.g., int * would become int **). This action will always apply a default sized pointer. Otherwise you can drag one of the other pointer types from the Data Type Manager window. With existing pointer data, the base type of that pointer may be changed simply by applying another type onto the pointer (e.g., applying byte to default pointer becomes db *). If you do not want this pointer stacking behavior to happen, it is best to clear the code unit(s) before applying a data type via drag-n-drop or key-binding actions.
Cycling a Component Data Type
Some data types are part of a cycle group. A cycle group is a collection of data types that are similar and are commonly associated with one another. Cycling a data type facilitates changing a component from one data type to the next data type in the same group. Each cycle group has a short-cut key associated with the group. Pressing the short-cut key cycles from the current data type to the next one in the group. For example, the b key is associated with the Byte cycle group. This group is Byte, Word, DWord, and QWord.
A single row of the component table must be selected to cycle a data type.
Union or Aligned Structure
The first data type in a cycle group can be added to the end of a structure as a new component.
To add a data type using a cycle group key:
- Select the last row (the blank row) of the component table.
- Press the short-cut key for the desired cycle group. For example, the b key will add a Byte; the f key will add a Float; the apostrophe key will add an Ascii.
Cycle groups can also be applied from the component table's popup menu under Cycle.
To cycle a component's data type to another one in the same group:
- Select the component in the table.
- Press the cycle group key until the data type has cycled to the desired data type. For example, if the current data type is a Byte, pressing the b key twice would change it to DWord.
When the current component data type is not in the cycle group of the desired data type, pressing the cycle group key of the desired data type will change the component to the first data type in the desired cycle group. The data type can then be cycled to any other data type in the group.
Unaligned Structure
Cycling is implemented similar to how it is implemented in an aligned structure. The only exception is that the user can only cycle to data types that will fit within the data boundary of the current component. If Undefined bytes follow the selected component, the Undefined bytes can be replaced by cycling the data type to a larger sized data type. Likewise, cycling to a smaller data type will add Undefined bytes after the component being cycled. However, the last component is not restricted to a particular size.
Drag and Drop Basics
Data types can be dragged from the Data Type Manager to the component table in the Structure Editor. A regular drag and drop results in the component in the editor being replaced by the one being dragged. Holding the Ctrl key during the drag and drop causes the dragged data type to be inserted instead of being replaced.
Known Problem: Holding the Ctrl key to perform an insert of a data type does not currently work on a Mac. On a Mac try using the Alt key to insert rather than the Ctrl key. The "+" should then appear at the drop site.
When a data type is dropped on a pointer component, the component becomes a pointer of that data type instead of simply being replaced by that data type. For example, dropping a Byte on a Pointer results in a Byte*, which is a pointer to a Byte. Drag and Drop is discussed further in Adding a Data Type, Inserting a Data Type, and Replacing a Data Type.
Favorites Basics
Favorite data types are defined from the Data Type Manager dialog. In the Data Editor, favorites are available through the popup menu in the component table. Applying a favorite data type is similar to dropping a data type. Favorites can be used to insert a component of that data type or to replace a component's data type. Favorites can only be applied to a contiguous selection. Therefore, individual favorites are only enabled when they can be applied (i.e. they fit at the selection and the selection is contiguous).
When a favorite data type is applied to a pointer component, the component becomes a pointer of that data type instead of simply being replaced by that data type.
If you right mouse click on a component where there is no selection, the selection becomes a single component selection containing that component and the popup menu will appear.
Favorites are discussed further in Adding a Data Type, and Replacing a Data Type.
Adding a Data Type
A data type can be added as a component by replacing Undefined bytes. When editing an unaligned structure, there must be enough Undefined bytes for the data type to replace. A data type can also be added to the end of a structure or union.
Drag and Drop
Drag a data type from the data type manager to the empty row at the end of the component table and drop it. The data type is added to the end of the structure in the editor.
If the data type can be various sizes, the user is prompted for the desired size. The following illustrates the dialog due to the drag and drop of a string.
Simply enter the number of bytes desired for the data type and press the Enter key or click the OK button.
For information about drag and drop with pointers, see Drag and Drop Basics.
Favorites
Right mouse click on the empty row at the end of the table and pull right to see the Favorites. Select the favorite from the popup and it is added as the last component.
For information about Pointers as a Favorite, see Favorites Basics.
Inserting a Data Type
In an aligned structure or a union, a data type can be inserted as a new component.
Drag and Drop
- While holding down the Ctrl key, drag the data type you want to insert from the data type manager. As you drag it over the components in the structure editor, the drag icon will have a "+" on it indicating insert mode.
- Release the mouse button when you are on the desired component and the dragged data type is inserted before it.
Known Problem: Holding the Ctrl key to perform an insert of a data type does not currently work on a Mac. On a Mac try using the Alt key to insert rather than the Ctrl key. The "+" should then appear at the drop site.
For information about drag and drop with pointers, see Drag and Drop Basics.
Replacing a Data Type
A component can have its data type replaced with a different data type. If an unaligned structure is being edited then Undefined bytes are created or consumed as necessary to maintain the position of other components within the structure. For unions and aligned structures, the data type simply changes for the component and the overall size is adjusted accordingly.
Drag and Drop
Single Component Selected
Drag a data type to a single selected component in the editor or to a non-selected component in the editor. If the mouse pointer is a 'circle with a slash' then the data type cannot be dropped to replace the component. This is probably because the data type being dropped won't fit in the structure in place of the original component. If editing a union or an aligned structure the data type should always fit and the drop is allowed. If editing an unaligned structure, the component is replaced only if the new component will fit. (see Effect of Changing a Component's Size)
Contiguous Selection of Multiple Components
Drag a data type to a block of selected components. Whether the structure is aligned or unaligned doesn't matter when dropping a data type on a block of selected components. This is because the new component (s) will occupy the same space as the currently selected components.
In a union, all selected components will be replaced with a single component containing the data type dropped.
In a structure, as many components of the dropped data type as will fit in the selection are created to replace the selection. In an unaligned structure any left over bytes in the selection will become Undefined bytes.
For information about drag and drop with pointers, see Drag and Drop Basics.
Favorites
Single Component Selected
If you right mouse click on a component where there is no selection, the selection becomes a single component selection containing that component and the popup menu will appear.
To replace a component's data type with a favorite data type, select it in the table, right mouse click and pick the favorite. Only favorites that will fit in place of the component will be enabled. (see Effect of Changing a Component's Size)
Contiguous Selection of Multiple Components
To replace a contiguous selection with a favorite data type, select it in the table, right mouse click and pick the favorite.
In a union, all selected components will be replaced with a single component containing the favorite data type.
In a structure, only favorites that will fit in place of the selection will be enabled. Just like with drag and drop, whether the structure is aligned or unaligned doesn't matter. The selection becomes as many of the data type as will fit and left over bytes become Undefined bytes for an unaligned structure.
For information about Pointers as a Favorite, see Favorites Basics.
Showing a Component's Data Type Category
Every component has a data type: Byte, Word, Float, etc.. The category is where that data type is located. Since you can have two data types with the same name in different locations (categories), the editor provides a way to see the category for any component's data type.
To see the category for a component:
- Select a single component.
- Right mouse click on the component in the table.
- From the popup menu, select Show Component Path.
- The category information appears in the editor's status line at the bottom of the dialog.
Editing a Component's Data Type
Another Data Type Editor can be brought up from within the Structure Data Type Editor for any component that is an editable data type, such as Structure, Union, or Enum. In addition, another Data Type Editor can be brought up for any component whose base data type is an editable data type. For example, a Typedef on a Structure would allow you to edit the Structure. Likewise, you can edit a Structure wherever the component is a Pointer to the Structure.
To display another editor for a component that has an editable data type:
- Select the component with a data type that is a structure, union or enum or that has one of them as its base data type.
- Right mouse click on the component in the table. Select Edit Component... from the popup.
- The editable data type for the selected component is displayed in a new data type editor.
Showing Numbers in Hexadecimal
The Component Table contains numeric fields such as the component's offset and length. The structure information area also shows the overall size and alignment of the structure. By default numbers are initially shown in decimal in the Structure Editor. There is a tool option, Show Numbers In Hex, that lets you override the default and set whether these numbers should be displayed in hexadecimal when an editor is initially displayed.
There is also a toolbar menu item in the editor that allows you to immediately change whether the numbers are displayed in hexadecimal or decimal. Changing this only affects the current editor where it is changed.
The Union Editor does not display offsets since they are always zero.
To switch between decimal and hexadecimal display of numeric values in the current editor:
- Right mouse click on the table.
- A check mark next to Show Numbers in Hexadecimal indicates that numbers are currently displayed in hex. If there is no checkmark, the numbers are currently shown in decimal.
- From the popup menu, select Show Numbers in Hexadecimal.
- The numbers being displayed will change from decimal to hexadecimal or vice versa. The check mark next to Show Numbers in Hexadecimal indicates whether the numbers are currently displayed in hexadecimal.
Structure and Union Editor Tool Options
The Structure and Union Editors add options to the tool. To view or edit the option settings:
- From the tool's menu select Edit
Tool Options... which displays the Tool Options Dialog.
- Open the Editors tree node.
- Click on either the Structure Editor or Union Editor tree node to view its options.
The StructureEditor and Union Editor tabs contains the following options:
Editor Option Functionality
Structure Editor Show Numbers In Hex If selected, the component offsets and lengths as well as the overall size and alignment of the structure will be displayed in hexadecimal when a new Structure Editor is initially displayed.
Otherwise, the lengths are initially in decimal.
Union Editor
Show Numbers In Hex If selected, the component lengths as well as the overall size and alignment of the union will be displayed in hexadecimal when a new Union Editor is initially displayed.
Otherwise, the lengths are initially in decimal.To select an option simply click on the check box.
Bitfield Editor (unaligned structures only)
The Bitfield Editor is used by the Structure Editor when adding or modifying bitfield components within unaligned structures to facilitate precise placement at the bit level. The Bitfield Editor is not supported for unions and aligned structures since automated packing is performed (i.e., bitfields are specified via datatype text entry within the structure/union table view). While editing an unaligned structure, the Structure Editor popup menu actions Add Bitfield and Edit Bitfield are used to launch the Bitfield Editor.
The Bitfield Editor includes a visual depiction of the storage allocation bytes and associated bits (8-bits per byte, with a left-to-right / msb-to-lsb sequence of 7..0 ). The displayed byte ordering as conveyed by the Byte Offset header will differ for big-endian vs. little-endian. This is done to ensure that bitfields which span byte boundaries will always visually appear as a consecutive range of bits. The Component Bits display provides both a popup menu and mouse assisted bitfield manipulations. Component labels are included within each component when space permits. The color legend indicates the bit color scheme reflecting Defined bitfields, Defined non-bitfields, Edit bitfield bits, Conflict bits and Undefined bits. A dot in the center of an Undefined bit indicates a padding bit not included within any defined component. Conflict bits correspond to the current edited bitfield where bits have been specified in conflict with an existing component.
While the Bitfield Editor is displayed local popup menu actions are provided which can facilitate additional component manipulations (e.g., Add Bitfield, Edit Bitfield, Delete). These actions relate to the component at the current mouse cursor location. Invoking either the Add Bitfield or Edit Bitfield local popup menu actions will immediately cancel the current bitfield operation if one is active.
A component zoom feature is provided which can allow the user to increase the visual bit size allowing for component labels to be shown as size permits. While with the mouse cursor is over a component, use mouse wheel while the Shift key is depressed.
Bitfield Parameters
Structure Offset of Allocation Unit - controls the minimum byte offset of the storage allocation unit represented by the bitfield edit view. This offset is controlled via the
and
buttons at the top of the bitfield editor.
Allocation Bytes - controls the size of the storage allocation unit to be utilized in the event a bit conflict exists and the user chooses to Move Conflicts. This numeric entry can be directly entered within the range of 1 through 16 bytes. The mouse wheel may also be used while the cursor is over this entry.
Bit Size - specifies the size of the bitfield in bits. This size may not exceed the size of the specified Base Datatype. This numeric entry can be directly entered or via the mouse wheel while the cursor is over this entry field or the rendered bitfield.
Bit Offset - specifies the offset of the rightmost bit of the bitfield within the displayed allocation unit. This numeric entry can be directly entered or via the mouse wheel while the cursor is over this entry field.
Base Datatype - (required) specifies the numeric datatype associated with the bitfield. Valid datatypes include primitive integer types (e.g., char, bool, int, etc.), enum types, and typedef types of integer or enum types. This input allows direct text input with auto-complete assistance or via full access to a datatype tree chooser by clicking the '...' button.
Field Name - (optional) specifies the structure component name to be assigned to the bitfield. This entry utilizes a simple text entry field.
Comment - (optional) specifies the structure component comment to be assigned to the bitfield. This entry utilizes a simple text entry field.
The bitfield offset and size may be fully specified by using the mouse. Clicking and dragging over the visual bit-range where the bitfield should reside will adjust these settings.
Within the Bitfield Editor the bit size may not exceed the size of the Base Datatype based upon the structure's associated compiler convention (i.e., data organization). Since archives use default integer type sizes which may differ from a target program's datatype sizing, the use of fixed-size base datatypes may be preferred. Otherwise, structure edits should be performed within the target program where datatype sizes may be larger. If an existing bitfield size exceeds the size of the base datatype within the associated data organization the "effective" bitfield size will be reduced. As with other components, structure component sizing may change when moving between a datatype archive and a target program.
It is important to note that the retained bitfield storage specification (byte offset, component byte size, bit offset) will utilize the smallest possible values while preserving bitfield positioning within the structure. The allocation unit offset and size conveyed by the editor are for editor use only.
Provided by: Data Type Manager Plugin