Margin basics

Margins are the sidebars on the side of your editor. When working with margins, you should absolutely remember the following stuff:

  • Margin creation: don’t!
    You don’t have to create margins – as you would normally do to make objects. They are just there, but invisible by default. How many margins exist? By default you’ve got five. But since QScintilla 2.10 you can change it simply with the function setMargins(nr_of_margins). The function margins() returns the current amount.
     
  • Margin identifier: 0, 1, 2, ..
    Each margin is identified by a unique number. Counting starts from zero.
     
  • Margin visibility: width ≠ 0
    Normally you’ve got 5 margins (unless you’ve called setMargins(nr_of_margins)) – but all are invisible to start with. If you want to make one or more visible, just give them a width > 0.
     
  • Margin type: NumberMargin, SymbolMargin, …
    Not all margins are equal. Several types exist.
     

Take a look at the following example. The figure shows an editor with four margins. Margin 0 is a line number margin, margin 1 and 3 are symbol margins and margin 2 is for short texts:

 

Margin type

setMarginType(margin_nr, margin_type)
Four margin types exist:

  • Line number margin
    I think it’s obvious what this one displays. Please keep in mind that the margin doesn’t resize automatically when the line number grows. So you’ve got to resize it manually if needed.
     
  • Symbol margin
    This margin can display custom symbols.
     
  • Folding margin
    The folding margin displays the folding symbols that are used for folding (-) and unfolding (+) code that has been styled for this.
     
  • Text margin
    The text margin displays text (duh..). The font size, family, color, .. are all selectable.
     

Later we’ll dive into each type, one-by-one.

 

Margin width

setMarginWidth(margin_nr, int_width)
This function sets the width of the specified margin in pixels.
 
setMarginWidth(margin_nr, string_width)
A string (for example “0000”) is used to calculate the needed margin width, based on its font style.
 
Please remember that there is NO function setVisible(..) to specify which margins you want to display. The margin width is used for that: a nonzero value makes the margin visible.

 

Margin colors

setMarginsForegroundColor(color)
To change the margin foreground (text) color to blue, fill in the following parameter value: QColor(“#ff0000ff”). Note that in older versions of QScintilla, the function name is setMarginForegroundColor – without the s. The new name actually makes more sense. There is no parameter margin_nr to single out a specific margin, so the function impacts on all margins!
 
setMarginsBackgroundColor(color)
In older versions, the function name has no s – same story.
 
setMarginBackgroundColor(margin_nr, color) – QScintilla 2.10 only!
This function applies to one single margin. Unfortunately, it won’t work always. Take the symbol margin for example. If you’ve defined the margin as a simple QsciScintilla.SymbolMargin, the function won’t do anything. You should define the margin as QsciScintilla.SymbolMarginColor for it to work.