Dev:2.4/Doc/How to/Add a Theme Colorのソースを表示

==Adding a Theme Color==

Adding a new color to Blender's GUI theme system is quite easy, but involves a few steps. I've cataloged them here as a quick walk-through. In this example I'm adding theme colors for the various types of sequence editor strips.


===1. Define names for the theme colors===


Here we need to give the theme colors defined names so we can refer to them in our code.

'''source/blender/include/BIF_resources.h'''

Add to the end of <code>enum {	TH_AUTO, TH_BUT_OUTLINE, ... }</code> your new theme colors, following the same naming scheme. Colors that are used in the GUI (i.e. consistent across window space types) should be added before the <code>TH_THEMEUI</code> define. Other window space specific colors should be added at the end.

<source lang="cpp">
	TH_NODE_GROUP,
	
	TH_SEQ_MOVIE,
	TH_SEQ_IMAGE,
	TH_SEQ_SCENE,
	...
</source>


===2. Create variables to store the colors in===


'''source/makesdna/DNA_userdef_types.h'''

This file contains the structs that get saved in SDNA, to the .B.blend user settings file. You need to add variables here to store the theme colors in when they are saved in the file. If the the colour you're adding is a cross-space UI theme color, add the necessary variables to struct ThemeUI, otherwise add them to <code>struct ThemeSpace</code>.

You will need to follow the DNA struct padding rules here.

<source lang="cpp">
	char movie[4], image[4], scene[4], audio[4];		// for sequence editor
	...
</source>


===3. Set up theme API and define color values for the default theme===


'''source/src/resources.c'''

<code>BIF_ThemeGetColorPtr()</code> is the function that finds the right color values in the User Preferences struct based on the theme color name. Find <code>BIF_ThemeGetColorPtr()</code> and add in the appropriate code, referencing the variables you just made in '''DNA_userdef_types.h''' . Again, refer to the existing code, and add your theme colors in the same places, depending on whether they are UI theme colors or window space theme colors.

<source lang="cpp">
		case TH_SEQ_MOVIE:
			cp= ts->movie; break;
		case TH_SEQ_IMAGE:
			cp= ts->image; break;
		...
</source>

<code>BIF_InitTheme()</code> defines the values of the new theme colors in the Default theme. Find the correct place there to add your new colors:

<source lang="cpp">
		/* space seq */
		btheme->tseq= btheme->tv3d;
		SETCOL(btheme->tseq.back, 	116, 116, 116, 255);
		SETCOL(btheme->tseq.movie, 	94, 165, 92, 255);
		SETCOL(btheme->tseq.image, 	39, 127, 137, 255);
		...
</source>

<code>BIF_ThemeColorsPup()</code> generates the theme color menu in the user preferences window. You also need to add your theme color names here so users can select and edit the theme colors themselves. Find the appropriate place and add in your new names.

<source lang="cpp">
		case SPACE_SEQ:
			str += sprintf(str, "Grid %%x%d|", TH_GRID);
			str += sprintf(str, "Window Sliders %%x%d|", TH_SHADE1);
			str += sprintf(str, "%%l|");
			str += sprintf(str, "Movie Strip %%x%d|", TH_SEQ_MOVIE);
			str += sprintf(str, "Image Strip %%x%d|", TH_SEQ_IMAGE);
			...
</source>

You can use

<source lang="cpp">
		str += sprintf(str, "%%l|");
</source>

to insert a separator in the menu.

===4. Set default values for the theme colors, for when opening an old .blend file===


Old .blend files (mainly the .B.blend) saved from before the theme color was added won't have any data for the new theme colors in its DNA.

'''source/src/usiblender.c'''

<code>init_userdef_file()</code> initializes the UserDef struct, which is where the theme colors are stored. You will need to initialize old files with default data if they're older than the current release.  So if the next release (that will contain your new theme colors) is version 2.42, then search for the section that says:

<source lang="cpp">
		if (G.main->versionfile <= 241) {
</source>

If your theme color does not store alpha, then a good way to check that the the color doesn't exist in the file is to check to see if alpha = 0 (if it doesn't use alpha, alpha should be set to 255 by default). These snippet of code will go through the themes stored in the .blend file and initialize the new values:

<source lang="cpp">
		bTheme *btheme;
		for (btheme= U.themes.first; btheme; btheme= btheme->next) {
			/* Sequence editor theme, check for alpha==0 is safe, then color was never set */
			if(btheme->tseq.movie[3]==0) {
				SETCOL(btheme->tseq.movie, 	94, 165, 92, 255);
				SETCOL(btheme->tseq.image, 	39, 127, 137, 255);
				
				...
			}
		}
</source>

Of course you can integrate this into any existing code that is there to handle the same thing.


===5. Make exceptions for special theme values===


If your theme color uses values that aren't the usual RGB triplet you'll need to make an exception for them in the theme UI display code, to show users the correct controls needed to manipulate the values. This is necessary if, for example, the theme color involves a user-defined alpha value, or if it's controlling an number value, such as the vertex point size, or if it's a choice between multiple options, such as the UI theme's draw type.

'''source/src/space.c'''

Make the relevant modifications in <code>info_user_themebuts()</code>. You can see examples of other exceptions underneath the line marked with

<source lang="cpp">
		/* first handle exceptions, special single values, row selection, etc */
</source>

If you just want to enable access to the alpha value, add your theme color name to the list in
	
<source lang="cpp">
		if ELEM7(th_curcol, TH_PANEL, TH_LAMP, ...
</source>

And use the relevant <code>ELEM()</code> macro for the amount of names.


===6. Update the Python API===


Python has access to the theme colors, in order to load and save themes via scripts. These should be updated too. If you're adding new UI theme colors you will need to edit <code>ThemeUI_getAttr()</code> and <code>ThemeUI_setAttr()</code>. In this example, we're adding theme colors for the sequence editor, so we need to add it in <code>ThemeSpace_getAttr()</code> and <code>ThemeSpace_setAttr()</code> instead. The procedure is just about identical for either.

'''python/api2_2x/windowTheme.c'''

In <code>ThemeSpace_getAttr()</code>, add entries for the new theme colors, using the same names as the variables created in DNA_userdef_types.h. If they're just simple RGB colors, they should be added before any of the "<code>else if</code>" lines that deal with single number values.
	
<source lang="text">
		...
		ELSEIF_TSP_RGBA( movie )
		ELSEIF_TSP_RGBA( image )
		...
</source>

You also seem to need to add an extra amount of 's' in the line
<source lang="text">
		attrib = Py_BuildValue("[sssssssssssssssssssssssssssssssssss]", "theme", ...
</source>
for how many new items you are adding, and also add your variables to that function in the same positions as you added them above.

<source lang="text">
		... "movie", "image", ... );
</source>

Then edit <code>ThemeSpace_setAttr()</code> as well. You can just copy and paste the <code>ELSEIF_TSP_RGBA</code> lines from above into the same position here.

'''python/api2_2x/doc/Theme.py'''

Also update the documentation file with the new variables in the same locations in either <code>class ThemeUI</code> or <code>class ThemeSpace</code>


===7. Use the theme color in your code!===

To set the current OpenGL color to your theme color use the function:
<source lang="cpp">
	void 	BIF_ThemeColor(int colorid);
</source>
as
<source lang="cpp">
	BIF_ThemeColor(TH_SEQ_MOVIE);
</source>

With whatever theme color name you like. In BIF_resources.h, you can also see other functions such as:

<source lang="cpp">void 	BIF_ThemeColorShade(int colorid, int offset);</source>

Sets the current OpenGL color to the theme color, but darkened or lightened by the specified amount (offset)


<source lang="cpp">void	BIF_ThemeColorShadeAlpha(int colorid, int coloffset, int alphaoffset);</source>

	Sets the current OpenGL color to the theme color, darkened or lightened by the specified amount (offset) and with less or more alpha (alphaoffset)


<source lang="cpp">void 	BIF_ThemeColorBlend(int colorid1, int colorid2, float fac);</source>

	Sets the current OpenGL color to a blend between two theme colors (colorid1, colorid2), blended with a specified proportion of the first to the second (fac)


<source lang="cpp">void    BIF_ThemeColorBlendShade(int colorid1, int colorid2, float fac, int offset);</source>

	Sets the current OpenGL color to a blend between two theme colors (colorid1, colorid2), blended with a specified proportion of the first to the second (fac), and darkened or lightened by a specified amount (offset)


There are more theme color functions, to return the color's actual numeric values rather than setting it as the current OpenGL drawing color, and to get a theme color from a specified window space type. See '''source/include/BIF_resources.h''' for all of the available functions you can use.

[[Category:Development]]
[[Category:Theming]]

[[Category:Script]]