The Vector Properties Dialog¶

Single Symbol Renderer¶

The Single Symbol renderer is used to render all features of the layer using a single user-defined symbol. See The Symbol Selector for further information about symbol representation.

Single symbol line properties

No Symbols Renderer¶

The No Symbols renderer is a special use case of the Single Symbol renderer as it applies the same rendering to all features. Using this renderer, no symbol will be drawn for features, but labeling, diagrams and other non-symbol parts will still be shown.

Selections can still be made on the layer in the canvas and selected features will be rendered with a default symbol. Features being edited will also be shown.

This is intended as a handy shortcut for layers which you only want to show labels or diagrams for, and avoids the need to render symbols with totally transparent fill/border to achieve this.

Categorized Renderer¶

The Categorized renderer is used to render the features of a layer, using a user-defined symbol whose aspect reflects the discrete values of a field or an expression. The Categorized menu allows you to

• select an existing field (using the Column listbox) or

• type or build an expression using the ^{Set column expression}. The expression used to classify features can be of any type; it can for example:

  • be a comparison, e.g. myfield >= 100, $id = @atlas_featureid, myfield % 2 = 0, within( $geometry, @atlas_geometry ). In this case, QGIS returns values 1 (True) and 0 (False).

  • combine different fields, e.g. concat( field1, ' ', field2 ) particularly useful when you want to process classification on two or more fields simultaneously.

  • be a calculation on fields, e.g. myfield % 2, year( myfield ) field_1 + field_2.

  • be used to transform linear values in discrete classes, e.g.:

    CASE WHEN x > 1000 THEN 'Big' ELSE 'Small' END

  • combine several discrete values in one single category, e.g.:

    CASE
    WHEN building IN ('residence', 'mobile home') THEN 'residential'
    WHEN building IN ('commercial', 'industrial') THEN 'Commercial and Industrial'
    END

  Note

  While you can use any kind of expression to categorize features, for some complex expressions it might be simpler to use rule-based rendering.

• the symbol (using the The Symbol Selector dialog) which will be used as base symbol for each class;

• the range of colors (using the Color ramp listbox) from which color applied to the symbol is selected.

Then click on [Classify] button to create classes from the distinct value of the attribute column. Each class can be disabled unchecking the checkbox at the left of the class name.

To change symbol, value and/or label of the class, just double click on the item you want to change.

Right-click shows a contextual menu to Copy/Paste, Change color, Change transparency, Change output unit, Change symbol width.

The example in figure_categorized_symbology shows the category rendering dialog used for the rivers layer of the QGIS sample dataset.

Categorized Symbolizing options

Graduated Renderer¶

The Graduated renderer is used to render all the features from a layer, using an user-defined symbol whose color or size reflects the assignment of a selected feature’s attribute to a class.

Like the Categorized Renderer, the Graduated Renderer allows you to define rotation and size scale from specified columns.

Also, analogous to the Categorized Renderer, it allows you to select:

• The attribute (using the Column listbox or the ^{Set column expression} function)
• The symbol (using the Symbol selector dialog)
• The legend format and the precision
• The method to use to change the symbol: color or size
• The colors (using the color Ramp list) if the color method is selected
• The size (using the size domain and its unit)

Then you can use the Histogram tab which shows an interactive histogram of the values from the assigned field or expression. Class breaks can be moved or added using the histogram widget.

Back to the Classes tab, you can specify the number of classes and also the mode for classifying features within the classes (using the Mode list). The available modes are:

• Equal Interval: each class has the same size (e.g. values from 0 to 16 and 4 classes, each class has a size of 4);
• Quantile: each class will have the same number of element inside (the idea of a boxplot);
• Natural Breaks (Jenks): the variance within each class is minimal while the variance between classes is maximal;
• Standard Deviation: classes are built depending on the standard deviation of the values;
• Pretty Breaks: Computes a sequence of about n+1 equally spaced nice values which cover the range of the values in x. The values are chosen so that they are 1, 2 or 5 times a power of 10. (based on pretty from the R statistical environment http://astrostatistics.psu.edu/datasets/R/html/base/html/pretty.html)

The listbox in the center part of the Style tab lists the classes together with their ranges, labels and symbols that will be rendered.

Click on Classify button to create classes using the chosen mode. Each classes can be disabled unchecking the checkbox at the left of the class name.

To change symbol, value and/or label of the class, just double click on the item you want to change.

Right-click shows a contextual menu to Copy/Paste, Change color, Change transparency, Change output unit, Change symbol width.

The example in figure_graduated_symbology shows the graduated rendering dialog for the rivers layer of the QGIS sample dataset.

Graduated Symbolizing options

Proportional Symbol and Multivariate Analysis¶

Proportional Symbol and Multivariate Analysis are not rendering types available from the Style rendering drop-down list. However with the Size Assistant options applied over any of the previous rendering options, QGIS allows you to display your point and line data with such representation.

Creating proportional symbol

Proportional rendering is done by first applying to the layer the Single Symbol Renderer. Once you set the symbol, at the upper level of the symbol tree, the Data-defined override button available beside Size or Width options (for point or line layers respectively) provides tool to create proportional symbology for the layer. An assistant is moreover accessible through the menu to help you define size expression.

Varying size assistant

The assistant lets you define:

• The attribute to represent, using the Field listbox or the ^{Set column expression} function (see Expressions)
• the scale method of representation which can be ‘Flannery’, ‘Surface’ or ‘Radius’
• The minimum and maximum size of the symbol
• The range of values to represent: The down pointing arrow helps you fill automatically these fields with the minimum (or zero) and maximum values returned by the chosen attribute or the expression applied to your data.
• An unique size to represent NULL values.

To the right side of the dialog, you can preview the features representation within a live-update widget. This representation is added to the layer tree in the layer legend and is also used to shape the layer representation in the print composer legend item.

The values presented in the varying size assistant above will set the size ‘Data-defined override’ with:

coalesce(scale_exp(Importance, 1, 20, 2, 10, 0.57), 1)

Creating multivariate analysis

A multivariate analysis rendering helps you evaluate the relationship between two or more variables e.g., one can be represented by a color ramp while the other is represented by a size.

The simplest way to create multivariate analysis in QGIS is to first apply a categorized or graduated rendering on a layer, using the same type of symbol for all the classes. Then, clicking on the symbol [Change] button above the classification frame, you get the The Symbol Selector dialog from which, as seen above, you can activate and set the size assistant option either on size (for point layer) or width (for line layer).

Like the proportional symbol, the size-related symbol is added to the layer tree, at the top of the categorized or graduated classes symbols. And both representation are also available in the print composer legend item.

Multivariate example

Rule-based Renderer¶

The Rule-based renderer is used to render all the features from a layer, using rule-based symbols whose aspect reflects the assignment of a selected feature’s attribute to a class. The rules are based on SQL statements. The dialog allows rule grouping by filter or scale, and you can decide if you want to enable symbol levels or use only the first-matched rule.

To create a rule, activate an existing row by double-clicking on it, or click on ‘+’ and click on the new rule. In the Rule properties dialog, you can define a label for the rule. Press the button to open the expression string builder. In the Function List, click on Fields and Values to view all attributes of the attribute table to be searched. To add an attribute to the field calculator Expression field, double click on its name in the Fields and Values list. Generally, you can use the various fields, values and functions to construct the calculation expression, or you can just type it into the box (see Expressions). You can create a new rule by copying and pasting an existing rule with the right mouse button. You can also use the ‘ELSE’ rule that will be run if none of the other rules on that level matches. Since QGIS 2.8 the rules appear in a tree hierarchy in the map legend. Just double-click the rules in the map legend and the Style tab of the layer properties appears showing the rule that is the background for the symbol in the tree.

The example in figure_rule_based_symbology shows the rule-based rendering dialog for the rivers layer of the QGIS sample dataset.

Rule-based Symbolizing options

Point displacement Renderer¶

The Point Displacement renderer works to visualize all features of a point layer, even if they have the same location. To do this, the symbols of the points are placed on a displacement circle around one center symbol or on several concentric circles.

Point displacement dialog

Inverted Polygon Renderer¶

The Inverted Polygon renderer allows user to define a symbol to fill in outside of the layer’s polygons. As above you can select subrenderers, namely Single symbol, Graduated, Categorized, Rule-Based or 2.5D renderer.

Inverted Polygon dialog

Heatmap Renderer¶

With the Heatmap renderer you can create live dynamic heatmaps for (multi)point layers. You can specify the heatmap radius in pixels, mm or map units, choose and edit a color ramp for the heatmap style and use a slider for selecting a trade-off between render speed and quality. You can also define a maximum value limit and give a weight to points using a field or an expression. When adding or removing a feature the heatmap renderer updates the heatmap style automatically.

Heatmap dialog

2.5D Renderer¶

Using the 2.5D renderer it’s possible to create a 2.5D effect on your layer’s features. You start by choosing a Height value (in map units). For that you can use a fixed value, one of your layer’s fields, or an expression. You also need to choose an Angle (in degrees) to recreate the viewer position (0° means west, growing in counter clock wise). Use advanced configuration options to set the Roof Color and Wall Color. If you would like to simulate solar radiation on the features walls, make sure to check the Shade walls based on aspect option. You can also simulate a shadow by setting a Color and Size (in map units).

2.5D dialog

Symbols levels¶

For renderers that allow stacked symbol layers (only heatmap doesn’t) there is an option to control the rendering order of each symbol’s levels.

For most of the renderers, you can access the Symbols levels option by clicking the [Advanced] button below the saved symbols list and choosing Symbol levels. For the Rule-based Renderer the option is directly available through [Symbols levels] button, while for Point displacement Renderer renderer the same button is inside the Rendering settings dialog.

To activate symbols levels, select the Enable symbol levels. Each row will show up a small sample of the combined symbol, its label and the individual symbols layer divided into columns with a number next to it. The numbers represent the rendering order level in which the symbol layer will be drawn. Lower values levels are drawn first, staying at the bottom, while higher values are drawn last, on top of the others.

Symbol levels dialog

Symbol levels activated (A) and deactivated (B) difference

Draw effects¶

In order to improve layer rendering and avoid (or at least reduce) the resort to other software for final rendering of maps, QGIS provides another powerful functionality: the Draw Effects options, which adds paint effects for customizing the visualization of vector layers.

The option is available in the Layer Properties –> Style dialog, under the Layer rendering group (applying to the whole layer) or in symbol layer properties (applying to corresponding features). You can combine both usage.

Paint effects can be activated by checking the Draw effects option and clicking the ^{Customize effects} button, that will open the Effect Properties Dialog (see figure_effects_source). The following effect types, with custom options are available:

• Source: Draws the feature’s original style according to the configuration of the layer’s properties. The transparency of its style can be adjusted.

  

  Draw Effects: Source dialog

• Blur: Adds a blur effect on the vector layer. The options that someone can change are the Blur type (Stack or Gaussian blur), the strength and transparency of the blur effect.

  

  Draw Effects: Blur dialog

• Colorize: This effect can be used to make a version of the style using one single hue. The base will always be a grayscale version of the symbol and you can use the Grayscale to select how to create it (options are: ‘lightness’, ‘luminosity’ and ‘average’). If Colorise is selected, it will be possible to mix another color and choose how strong it should be. You can also control the Brightness, contrast and saturation levels of the resulting symbol.

  

  Draw Effects: Colorize dialog

• Drop Shadow: Using this effect adds a shadow on the feature, which looks like adding an extra dimension. This effect can be customized by changing the offset degrees and radius, determining where the shadow shifts towards to and the proximity to the source object. Drop Shadow also has the option to change the blur radius, the transparency and the color of the effect.

  

  Draw Effects: Drop Shadow dialog

• Inner Shadow: This effect is similar to the Drop Shadow effect, but it adds the shadow effect on the inside of the edges of the feature. The available options for customization are the same as the Drop Shadow effect.

  

  Draw Effects: Inner Shadow dialog

• Inner Glow: Adds a glow effect inside the feature. This effect can be customized by adjusting the spread (width) of the glow, or the Blur radius. The latter specifies the proximity from the edge of the feature where you want any blurring to happen. Additionally, there are options to customize the color of the glow, with a single color or a color ramp.

  

  Draw Effects: Inner Glow dialog

• Outer Glow: This effect is similar to the Inner Glow effect, but it adds the glow effect on the outside of the edges of the feature. The available options for customization are the same as the Inner Glow effect.

  

  Draw Effects: Outer Glow dialog

• Transform: Adds the possibility of transforming the shape of the symbol. The first options available for customization are the Reflect horizontal and Reflect vertical, which actually create a reflection on the horizontal and/or vertical axes. The 4 other options are:

  • Shear: slants the feature along the x and/or y axis
  • Scale: enlarges or minimizes the feature along the x and/or y axis by the given percentage
  • Rotation: turns the feature around its center point
  • and Translate changes the position of the item based on a distance given on the x and/or the y axis.
  

  Draw Effects: Transform dialog

There are some common options available for all draw effect types. Transparency and Blend mode options work similar to the ones described in Layer rendering and can be used in all draw effects except for the transform one.

One or more draw effects can used at the same time. You activate/deactivate an effect using its checkbox in the effects list. You can change the selected effect type by using the Effect type option. You can reorder the effects using ^{Move up} and ^{Move down} buttons, and also add/remove effects using the ^{Add effect} and ^{Remove effect} buttons.

There is also a Draw mode option available for every draw effect, and you can choose whether to render and/or to modify the symbol. Effects render from top to bottom.’Render only’ mode means that the effect will be visible while the ‘Modify only’ mode means that the effect will not be visible but the changes that it applies will be passed to the next effect (the one immediately below). The ‘Render and Modify’ mode will make the effect visible and pass any changes to the next effect. If the effect is in the top of the effects list or if the immediately above effect is not in modify mode, then it will use the original source symbol from the layers properties (similar to source).

Text tab¶

In the Text tab, you can define the Font, Style, and Size of your labels’ text (see Figure_labels). There are options available to set the labels’ Color and Transparency. Use the Type case option to change the capitalization style of the text. You have the possibility to render the text as ‘All uppercase’, ‘All lowercase’ or ‘Capitalize first letter’. In Spacing, you can change the space between words and between individual letters. Finally, use the Blend mode option to determine how your labels will mix with the map features below them (see more about it in Blending Modes).

The Apply label text substitutes option gives you ability to specify a list of texts to substitute to texts in feature labels (e.g., abbreviating street types). Replacement texts are thus used to display labels in the map canvas. Users can also export and import lists of substitutes to make reuse and sharing easier.

Formatting tab¶

In the Formatting tab, you can define a character for a line break in the labels with the Wrap on character option. You can also format the Line Height and the alignment. For the latter, typical values are available (left, right, and center), plus Follow label placement for point layers. When set to this mode, text alignment for labels will be dependent on the final placement of the label relative to the point. E.g., if the label is placed to the left of the point, then the label will be right aligned, while if it is placed to the right, it will be left aligned.

For line vector layers you can include Line directions symbols to help determine the lines directions. They work particularly well when used with the curved or Parallel placement options from the Placement tab. There are options to set the symbols position, and to reverse direction.

Use the Formatted numbers option to format numeric labels. You can set the number of Decimal places. By default, 3 decimal places will be used. Use the Show plus sign if you want to show the plus sign in positive numbers.

Buffer tab¶

To create a buffer around the labels, activate the Draw text buffer checkbox in the Buffer tab. You can set the buffer’s Size, color, and Transparency. The buffer expands from the label’s outline , so, if the color buffer’s fill checkbox is activated, the buffer interior is filled. This may be relevant when using partially transparent labels or with non-normal blending modes, which will allow seeing behind the label’s text. Deactivating color buffer’s fill checkbox (while using totally transparent labels) will allow you to create outlined text labels.

Background tab¶

In the Background tab, you can define with Size X and Size Y the shape of your background. Use Size type to insert an additional ‘Buffer’ into your background. The buffer size is set by default here. The background then consists of the buffer plus the background in Size X and Size Y. You can set a Rotation where you can choose between ‘Sync with label’, ‘Offset of label’ and ‘Fixed’. Using ‘Offset of label’ and ‘Fixed’, you can rotate the background. Define an Offset X,Y with X and Y values, and the background will be shifted. When applying Radius X,Y, the background gets rounded corners. Again, it is possible to mix the background with the underlying layers in the map canvas using the Blend mode (see Blending Modes).

Shadow tab¶

Use the Shadow tab for a user-defined Drop shadow. The drawing of the background is very variable. Choose between ‘Lowest label component’, ‘Text’, ‘Buffer’ and ‘Background’. The Offset angle depends on the orientation of the label. If you choose the Use global shadow checkbox, then the zero point of the angle is always oriented to the north and doesn’t depend on the orientation of the label. You can influence the appearance of the shadow with the Blur radius. The higher the number, the softer the shadows. The appearance of the drop shadow can also be altered by choosing a blend mode.

Placement tab¶

Choose the Placement tab for configuring label placement and labeling priority. Note that the placement options differ according to the type of vector layer, namely point, line or polygon.

Placement for line layers¶

Label options for line layers include Parallel, Curved or Horizontal. For the Parallel and Curved options, you can set the position to Above line, On line and Below line. It’s possible to select several options at once. In that case, QGIS will look for the optimal label position. For Parallel and curved placement options, you can also use the line orientation for the position of the label. Additionally, you can define a Maximum angle between curved characters when selecting the Curved option (see Figure_labels_placement_line).

Label placement examples in lines

For all three placement options, in Repeat, you can set up a minimum distance for repeating labels. The distance can be in mm or in map units.

Placement for polygon layers¶

You can choose one of the following options for placing labels in polygons (see figure_labels_placement_polygon):

• Offset from centroid,
• Horizontal (slow),
• Around centroid,
• Free (slow),
• Using perimeter,
• and Using perimeter (curved).

In the Offset from centroid settings you can specify if the centroid is of the visible polygon or whole polygon. That means that either the centroid is used for the polygon you can see on the map or the centroid is determined for the whole polygon, no matter if you can see the whole feature on the map. You can place your label within a specific quadrant, and define offset and rotation.

The Around centroid setting places the label at a specified distance around the centroid. Again, you can define visible polygon or whole polygon for the centroid.

With the Horizontal (slow) or Free (slow) options, QGIS places at the best position either a horizontal or a rotated label inside the polygon.

With the Using perimeter option, the label will be drawn next to the polygon boundary. The label will behave like the parallel option for lines. You can define a position and a distance for the label. For the position, Above line, On line, Below line and Line orientation dependent position are possible. You can specify the distance between the label and the polygon outline, as well as the repeat interval for the label.

The Using perimeter (curved) option helps you draw the label along the polygon boundary, using a curved labeling. In addition to the parameters available with Using perimeter setting, you can set the Maximum angle between curved characters polygon, either inside or outside.

Label placement examples in polygons

In the priority section you can define the priority with which labels are rendered for all three vector layer types (point, line, polygon). This placement option interacts with the labels from other vector layers in the map canvas. If there are labels from different layers in the same location, the label with the higher priority will be displayed and the others will be left out.

Rendering tab¶

In the Rendering tab, you can tune when the labels can be rendered and their interaction with other labels and features.

Under Label options, you find the scale-based and the Pixel size-based visibility settings.

The Label z-index determines the order in which labels are rendered, as well in relation with other feature labels in the layer (using data-defined override expression), as with labels from other layers. Labels with a higher z-index are rendered on top of labels (from any layer) with lower z-index.

Additionally, the logic has been tweaked so that if 2 labels have matching z-indexes, then:

• if they are from the same layer, the smaller label will be drawn above the larger label
• if they are from different layers, the labels will be drawn in the same order as their layers themselves (ie respecting the order set in the map legend).

Note that this setting doesn’t make labels to be drawn below the features from other layers, it just controls the order in which labels are drawn on top of all the layer’s features.

While rendering labels and in order to display readable labels, QGIS automatically evaluates the position of the labels and can hide some of them in case of collision. You can however choose to Show all labels for this layer (including colliding labels) in order to manually fix their placement.

With data-defined expressions in Show label and Always Show you can fine tune which labels should be rendered.

Under Feature options, you can choose to label every part of a multi-part feature and limit the number of features to be labeled. Both line and polygon layers offer the option to set a minimum size for the features to be labeled, using Suppress labeling of features smaller than. For polygon features, you can also filter the labels to show according to whether they completely fit within the feature or not. For line features, you can choose to Merge connected lines to avoid duplicate labels, rendering a quite airy map in conjunction with the Distance or Repeat options in Placement tab.

From the Obstacles frame, you can manage the covering relation between labels and features. Activate the Discourage labels from covering features option to decide whether features of the layer should act as obstacles for any label (including labels from other features in the same layer). An obstacle is a feature QGIS tries as far as possible to not place labels over. Instead of the whole layer, you can define a subset of features to use as obstacles, using the ^{data-defined override} control next to the option.

The priority control slider for obstacles allows you to make labels prefer to overlap features from certain layers rather than others. A Low weight obstacle priority means that features of the layer are less considered as obstacles and thus more likely to be covered by labels. This priority can also be data-defined, so that within the same layer, certain features are more likely to be covered than others.

For polygon layers, you can choose the type of obstacle features could be by minimising the labels placement:

• over the feature’s interior: avoids placing labels over the interior of the polygon (prefers placing labels totally outside or just slightly inside the polygon)
• or over the feature’s boundary: avoids placing labels over boundary of the polygon (prefers placing labels outside or completely inside the polygon). E.g., it can be useful for regional boundary layers, where the features cover an entire area. In this case, it’s impossible to avoid placing labels within these features, and it looks much better to avoid placing them over the boundaries between features.

The Label Toolbar¶

The Label Toolbar provides some tools to manipulate label or diagram properties, but only if the corresponding data-defined option is indicated (otherwise, buttons are disabled). Layer might also need to be in edit mode.

The Label toolbar

While for readability, label has been used below to describe the Label toolbar, note that when mentioned in their name, the tools work almost the same way with diagrams:

• ^{Pin/Unpin Labels And Diagrams} that has data-defined position. By clicking or draging an area, you pin label(s). If you click or drag an area holding Shift, label(s) are unpinned. Finally, you can also click or drag an area holding Ctrl to toggle the pin status of label(s).
• ^{Highlight Pinned Labels And Diagrams}. If the vector layer of the label is editable, then the highlighting is green, otherwise it’s blue.
• ^{Move Label And Diagram} that has data-defined position. You just have to drag the label to the desired place.
• ^{Show/Hide Labels And Diagrams} that has data-defined visbility. If you click or drag an area holding Shift, then label(s) are hidden. When a label is hidden, you just have to click or drag an area around the feature’s point to restore its visibility.
• ^{Rotate Label}. Click the label and move around and you get the text rotated.
• ^{Change Label}. It opens a dialog to change the clicked label properties; it can be the label itself, its coordinates, angle, font, size... as long as this property has been mapped to a field.

Customize the labels from the map canvas¶

Combined with the Label Toolbar, the data defined override setting helps you manipulate labels in the map canvas (move, edit, rotate). We now describe an example using the data-defined override function for the ^{Move label} function (see figure_labels_data_defined).

1. Import lakes.shp from the QGIS sample dataset.

2. Double-click the layer to open the Layer Properties. Click on Labels and Placement. Select Offset from centroid.

3. Look for the Data defined entries. Click the icon to define the field type for the Coordinate. Choose xlabel for X and ylabel for Y. The icons are now highlighted in yellow.

   

   Labeling of vector polygon layers with data-defined override

4. Zoom into a lake.

5. Set editable the layer using the ^{Toggle Editing} button.

6. Go to the Label toolbar and click the icon. Now you can shift the label manually to another position (see figure_labels_move). The new position of the label is saved in the xlabel and ylabel columns of the attribute table.

7. Using The Geometry Generator with the expression below, you can also add a linestring symbol layer to connect each lake to its moved label:

   make_line( centroid( $geometry ), make_point( "xlabel", "ylabel" ) )

   

   Moved labels

Common settings¶

Regardless the type of widget applied to the field, there are some common properties you can set to control whether and how a field can be edited:

• Editable: uncheck this to set the field read-only (not manually modifiable) when the layer is in edit mode. Note that checking this setting doesn’t override any edit limitation from the provider.

• Label on top: places the field name above or beside the widget in the feature form

• Default value: for new features, automatically populates by default the field with a predefined value or an expression-based one. For example, you can:

  • use $x, $length, $area to populate a field with the feature’s x coordinate, length, area or any geometric information at its creation;
  • incremente a field by 1 for each new feature using maximum("field")+1;
  • save the feature creation datetime using now();
  • use variables in expressions, making it easier to e.g. insert the operator name (@user_full_name), the project file path (@project_path), ...

  A preview of the resulting default value is displayed at the bottom of the widget.

  Note

  The Default value option is not aware of the values in any other field of the feature being created so it won’t be possible to use an expression combining any of those values i.e using an expression like concat(field1, field2) may not work.

• Constraints: you can constrain the value to insert in the field. This constraint can be:

  • Not null: force the user to provide a value

  • based on a custom expression: e.g. regexp_match(col0,'A-Za-z') to ensure that the value of the field col0 has only alphabetical letter.

    A short description of the constraint can be added and will be displayed at the top of the form as a warning message when the value supplied does not match the constraint.

Edit widgets¶

The available widgets are:

• Checkbox: Displays a checkbox, and you can define what attribute is added to the column when the checkbox is activated or not.
• Classification: Displays a combo box with the values used for classification, if you have chosen ‘unique value’ as legend type in the Style tab of the properties dialog.
• Color: Displays a color button allowing user to choose a color from the color dialog window.
• Date/Time: Displays a line field which can open a calendar widget to enter a date, a time or both. Column type must be text. You can select a custom format, pop-up a calendar, etc.
• Enumeration: Opens a combo box with values that can be used within the columns type. This is currently only supported by the PostgreSQL provider.
• External Resource: Uses a “Open file” dialog to store file path in a relative or absolute mode. It can also be used to display a hyperlink (to document path), a picture or a web page.
• File Name: Simplifies the selection by adding a file chooser dialog.
• Hidden: A hidden attribute column is invisible. The user is not able to see its contents.
• Photo: Field contains a filename for a picture. The width and height of the field can be defined.
• Range: Allows you to set numeric values from a specific range. The edit widget can be either a slider or a spin box.
• Relation Reference: This widget lets you embed the feature form of the referenced layer on the feature form of the actual layer. See Creating one or many to many relations.
• Text Edit (default): This opens a text edit field that allows simple text or multiple lines to be used. If you choose multiple lines you can also choose html content.
• Unique Values: You can select one of the values already used in the attribute table. If ‘Editable’ is activated, a line edit is shown with autocompletion support, otherwise a combo box is used.
• UUID Generator: Generates a read-only UUID (Universally Unique Identifiers) field, if empty.
• Value Map: A combo box with predefined items. The value is stored in the attribute, the description is shown in the combo box. You can define values manually or load them from a layer or a CSV file.
• Value Relation: Offers values from a related table in a combobox. You can select layer, key column and value column. Several options are available to change the standard behaviours: allow null value, order by value, allow multiple selections and use of autocompleter. The forms will display either a drop-down list or a line edit field when completer checkbox is enabled.
• Web View: Field contains a URL. The width and height of the field is variable.

The drag and drop designer¶

Choose Drag and drop designer from the Attribute editor layout combobox to layout the features form within QGIS. Then, drag and drop rows from the Fields frame to the Label panel to have fields added to your custom form.

You can also use categories (tab or group frames) to better structure the form. The first step is to use the icon to create a tab in which fields and groups will be displayed (see figure_fields_layout). You can create as many categories as you want. The next step will be to assign to each category the relevant fields, using the icon. You’d need to select the targeted category beforehand. You can use the same fields many times.

Dialog to create categories with the Attribute editor layout

You can configure tabs or groups with a double-click. QGIS opens a form in which you can:

• choose to hide or show the item label
• rename the category
• set over how many columns the fields under the category should be distributed
• enter an expression to control the category visibility. The expression will be re-evaluated everytime values in the form change and the tab or groupbox shown/hidden accordingly.
• show the category as a group box (only available for tabs)

With a double-click on a field label, you can also specify whether the label of its widget should be visible or not in the form.

In case the layer is involved in one to many relations (see Creating one or many to many relations), referencing layers are listed in the Relations frame and their form can be embedded in the current layer form by drag-and-drop. Like the other items, double-click the relation label to configure some options:

• choose to hide or show the item label
• show the link button
• show the unlink button

Provide an ui-file¶

The Provide ui-file option allows you to use complex dialogs made with Qt-Designer. Using a UI-file allows a great deal of freedom in creating a dialog. Note that, in order to link the graphical objects (textbox, combobox...) to the layer’s fields, you need to give them the same name.

Use the Edit UI to define the path to the file to use.

You’ll find some example in the Creating a new form lesson of the QGIS Training Manual. For more advanced information, see http://nathanw.net/2011/09/05/qgis-tips-custom-feature-forms-with-python-logic/.

Enhance your form with custom functions¶

QGIS forms can have a Python function that is called when the dialog is opened. Use this function to add extra logic to your dialogs. The form code can be specified in three different ways:

• load from the environment: use a function, for example in startup.py or from an installed plugin)
• load from an external file: a file chooser will appear in that case to allow you to select a Python file from your filesystem
• provide code in this dialog: a Python editor will appear where you can directly type the function to use.

In all cases you must enter the name of the function that will be called (open in the example below).

An example is (in module MyForms.py):

def open(dialog,layer,feature):
    geom = feature.geometry()
    control = dialog.findChild(QWidged,"My line edit")

Reference in Python Init Function like so: open