Using createCharStyle

From Scribus Wiki
Jump to navigation Jump to search
The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.

Someone asked about the syntax for createCharStyle() on the mail list. The information in the online manual is clearly less than enough to understand how to use this command. My first attempts at making use of it couldn't even get past the traceback message, and the problem with traceback is that it tends to be at best cryptic, and at worst totally unhelpful.

Here is a slight translation I have done of the command as listed in its synopsis:

scribus.createCharStyle("name","font",fontsize,"features","fillcolor",fillshade,"strokecolor",strokeshade,baselineoffset, shadowxoffset,shadowyoffset,outlinewidth,underlineoffset,underlinewidth,strikethruoffset,strikethruwidth,scaleh,scalev, tracking,"language")

What I want to do is take these elements one by one and explain something about each. Notice that each one of these is either in quotes or not. If an element is in quotes, a string is expected and should be in quotes. If there are no quotes, then a numerical value is expected, and mostly a float value is appropriate. You do not, for example, put 'name="NameOfStyle"', you just have "NameOfStyle" in its place between the quotes. As far as I know, single or double quotes can be used here.

My Method

What I did was to use a pre-existing script I had that created text frames and entered text. I then just inserted this element at some point wherever it was sure to be executed:

scribus.createCharStyle(yadayadayada)

The yadayadayada refers to gradually building up from left to right the commands and with success, adding more. One of the first things I could learn was that, even though the only required element was the name of the style, you can't just skip over elements. You have to consider how Scripter knows that a particular element corresponds to a particular feature, so this makes some sense.

So you then can recursively run this script, and then either look at your named style or try to apply it.

Command Elements

Only the first of these is said to be required, all others optional, however, you cannot skip over elements. For some strings, an appropriate entry might be a null string (""), but entering the number zero as a default may not work, for example, see fillshade below.

  • name – a string with the name of the style. Again, simply enter this as "myfont", not name="mystyle".
  • font – a string with the font name. The name of the font is as listed in File > Preferences > Fonts under Font Name. So an appropriate entry here might be "DejaVu Sans Book", not "DejaVu Sans".
  • fontsize – a numerical value (float). Simply enter the number with no quotes.
  • features – a string containing one or more of the following: inherit,bold,italic,underline,underlinewords,strike,superscript,subscript,outline,shadowed,allcaps,smallcaps. Inside the quotes, separate items by commas but no spaces. Presumably the bold and italic choices have no effect.
  • fillcolor – a string with a color from your color list.
  • fillshade – a numerical value. When you edit styles, you select a percentage, but here you use a decimal, so 1.0 = 100%, which you should enter for a default value.
  • strokecolor – a string with a color from your color list. The stroke color would be used for outline and also shadow if either are specified.
  • strokeshade – a numerical value for stroke shade, see fillshade.
  • baselineoffset – a numerical value. When you edit this within Scribus, you see this as a percentage. Not only is this a decimal, but an odd one. If you enter 3, you get an offset of 0.3%. To actually get 3%, you would enter 30.
  • shadowxoffset – a numerical value. Just as with baselineoffset, this is a numerical value, where 30 equals 3% displacement in the X direction. Negative values are valid. You would need to specify shadowed in features or do this manually later to see this offset.
  • shadowyoffset – a numerical value. See shadowxoffset.