kr_group.h

这是法国Kaleido公司提供了一个手机mmi设计平台

	/*
	<kaleidoc>
<filename>Group</filename>
<page>
<api>
	<class>Group</class>
	<method>setStoreKey</method>
	<java>void setStoreKey(String s)</java>
	<cpp>void setStoreKey(char* s)</cpp>
	<descr>
	<p>If a store Key is set for a group (often set by a populator in its init() method) the index of the accepted Option will automatically be added in the global store. This is useful to retrieve a previously accepted Option in a plug-in. </p>
	<p>In the C version, the ownership of the param string is NOT transferred to the Group, to allow the use of static strings.</p>
	</descr>
	</api>
</page>
</kaleidoc>
	*/
	void setStoreKey(char* s) {
		SAFE_FREE(fStoreKey);
		fStoreKey = xstrdup(s);
	}

	/*
	<kaleidoc>
<filename>Group</filename>
<page>
<api>
	<class>Group</class>
	<method>getBgSrcOff</method>
	<java>String getBgSrcOff()</java>
	<cpp>char* getBgSrcOff()</cpp>
	<descr>
	<p>Refer to the Group.setBgSrcOff() documentation for an explanation</p>
	<p>In the C version, the ownership of the returned string is not transferred to the caller.</p>
	<fp>Here is the precedence used to get the bgOff:
	1) the Option's BgOff
	2) the Group's BgOff</fp>
	</descr>
	</api>
</page>
</kaleidoc>
	*/
	char* getBgSrcOff() {
		return fBgSrcOff;
	}

	/*
	<kaleidoc>
<filename>Group</filename>
<page>
<api>
	<class>Group</class>
	<method>setBgSrcOff</method>
	<java>void setBgSrcOff(String bgsrcOff)</java>
	<cpp>void setBgSrcOff(char* bgsrcOff)</cpp>
	<descr>
	<p>When no background image url is found at the option level, the one stored at the group level is used instead. This is used to avoid duplicating the same pointer again and again at each options level. If an image is present at both levels, the one at the Option level is used rather than the one at the Group level. </p>
	<p>In the C version, the ownership of the param string is transferred to the Group.</p>
	</descr>
	</api>
</page>
</kaleidoc>
	*/
	void setBgSrcOff(char* bgsrcOff) {
		ASSERT_MEMORY_OWNERSHIP(this, bgsrcOff);
		SAFE_FREE(fBgSrcOff);
		fBgSrcOff = bgsrcOff;
	}

	/*
	<kaleidoc>
<filename>Group</filename>
<page>
<api>
	<class>Group</class>
	<method>getBgSrcOn</method>
	<java>String getBgSrcOn()</java>
	<cpp>char* getBgSrcOn()</cpp>
	<descr>
	<p>Refer to the Group.setBgSrcOff() documentation for an explanation</p>
	<p>In the C version, the ownership of the returned string is not transferred to the caller.</p>
	<fp>Here is the precedence used to get the bgOn:
	1) the Option's BgOn
	2) the Option's BgOff
	3) the Group's BgOn
	4) the Group's BgOff</fp>
	</descr>
	</api>
</page>
</kaleidoc>
	*/
	char* getBgSrcOn() {
		return fBgSrcOn == NULL ? fBgSrcOff : fBgSrcOn;
	}

	/*
	<kaleidoc>
<filename>Group</filename>
<page>
<api>
	<class>Group</class>
	<method>setBgSrcOn</method>
	<java>void setBgSrcOn(String bgsrcOn)</java>
	<cpp>void setBgSrcOn(char* bgsrcOn)</cpp>
	<descr>
	<p>Refer to the Group.setBgSrcOff() documentation for an explanation</p>
	<p>In the C version, the ownership of the param string is transferred to the Group.</p>
	</descr>
	</api>
</page>
</kaleidoc>
	*/
	void setBgSrcOn(char* bgsrcOn) {
		ASSERT_MEMORY_OWNERSHIP(this, bgsrcOn);
		SAFE_FREE(fBgSrcOn);
		fBgSrcOn = bgsrcOn;
	}

#ifdef USE_DEPRECATED
	boolean isCachePopulatorOptions() {//deprecated
		return fCacheRefreshPopulatorOptions;
	}
#endif

	/*
	<kaleidoc>
<filename>Group</filename>
<page>
<api>
	<class>Group</class>
	<method>setCacheRefreshPopulatorOptions</method>
	<cpp>void setCacheRefreshPopulatorOptions(boolean b)</cpp>
	<java>final public void setCacheRefreshPopulatorOptions(boolean b)</java>
	<descr>
	<p>After calling setCacheRefreshPopulatorOptions(true) -  GroupPopulator.postRestore() is a good place for that, KRuntime outdates the Group options (and the nb of options) in its cache at the begining of the activate phase.
	This means that the options will be cached for the whole Activate/Render Phase but will be outdated for the next activate phase and they will then be requested again to the populator when needed.
	This also means that the nb of option will be requested to the populator (by calling GroupPopulator.getNbOption()).
	So, options are refreshed at each activate/Render phase (by calling GroupPopulator.getOption(index)).</p>
	</descr>
	</api>
</page>
</kaleidoc>
	*/
	void setCacheRefreshPopulatorOptions(boolean b){
		fCacheRefreshPopulatorOptions=b;
	}

	/*
	<kaleidoc>
<filename>Group</filename>
<page>
<api>
	<class>Group</class>
	<method>isCacheRefreshPopulatorOptions</method>
	<cpp>boolean isCacheRefreshPopulatorOptions()</cpp>
	<java>final public boolean isCacheRefreshPopulatorOptions()</java>
	<descr>
	<p>This method is the accessor for the value set using Group.setCacheRefreshPopulatorOptions().</p>
	</descr>
	</api>
</page>
</kaleidoc>
	*/
	boolean isCacheRefreshPopulatorOptions() {
		return fCacheRefreshPopulatorOptions;
	}

	/*
	<kaleidoc>
<filename>Group</filename>
<page>
<api>
	<class>Group</class>
	<method>setCacheDeletePopulatorOptions</method>
	<cpp>void setCacheDeletePopulatorOptions(boolean b)</cpp>
	<java></java>
	<descr>
	<p>In the C version, after calling Group.setCacheDeletePopulatorOptions(true), KRuntime deletes unused options from the cache.
	This saves memory but takes more time because options needs to be instanciated again in the populator.
	This can generate new/deletes that fragments memory.</p>
	<note>Notice that the "delete" used here should be used to save memory, not to make an indirect refresh.
	This effectively makes some refresh on some options since some options are deleted and eventually recreated later but this does not apply to all options.</note>
	</descr>
	</api>
</page>
</kaleidoc>
	*/
	void setCacheDeletePopulatorOptions(boolean b){
		fCacheDeletePopulatorOptions=b;
	}

	/*
	<kaleidoc>
<filename>Group</filename>
<page>
<api>
	<class>Group</class>
	<method>isCacheDeletePopulatorOptions</method>
	<cpp>boolean isCacheDeletePopulatorOptions()</cpp>
	<java></java>
	<descr>
	<p>This method is the accessor for the value set using Group.setCacheDeletePopulatorOptions().</p>
	</descr>
	</api>
</page>
</kaleidoc>
	*/
	boolean isCacheDeletePopulatorOptions() {
		return fCacheDeletePopulatorOptions;
	}

	/*
	<kaleidoc>
<filename>Group</filename>
<page>
<api>
	<class>Group</class>
	<method>setCachePopulatorOptions</method>
	<cpp>void setCachePopulatorOptions(boolean doNotRefresh, boolean doNotDelete=true)</cpp>
	<java>final public void setCachePopulatorOptions(boolean cachePopulatorOptions)</java>
	<descr>
	<note>This method is deprecated. It stays in the documentation because it has been widely used.</note>
	<xref>grouprefreshing</xref>

	<p>After calling Group.setCachePopulatorOptions(false) -  GroupPopulator.postRestore() is a good place for that, KRuntime outdates the Group options in its cache at the begining of the activate phase.
	This means that the options will be cached for the whole Activate/Render Phase but will be outdated for the next activate phase.
	They will then be requested again to the populator when needed.
	So, options are refreshed at each activate/Render phase.</p>

	<p>In the C version, after calling Group.setCachePopulatorOptions(xxx, false), KRuntime deletes unused options from the cache.
	This saves memory but takes more time because options needs to be instanciated again in the populator.
	This can generate new/deletes that fragments memory.</p>
	<p>Default is Group.setCachePopulatorOptions(true, true)</p>
	<note>Notice that the "delete" used here should be used to save memory, not to make an indirect refresh.
	This effectively makes some refresh on some options since some options are deleted and eventually recreated later but this does not apply to all options.</note>

  <p>To change this deprecated method call to the new api, replace:</p>

  <code>setCachePopulatorOptions(doNotRefresh, doNotDelete=true)</code>
  <p>with</p>
  <code>setCacheRefreshPopulatorOptions(!doNotRefresh);
setCacheRefreshPopulatorNbOptions(!doNotRefresh);
setCacheDeletePopulatorOptions(!doNotDelete)
</code>

</descr>

	<notes></notes>
	<examples></examples>
	</api>
</page>
</kaleidoc>
	*/
	void setCachePopulatorOptions(boolean doNotRefresh, boolean doNotDelete=true) {// deprecated
		setCacheRefreshPopulatorOptions(!doNotRefresh);
		setCacheRefreshPopulatorNbOptions(!doNotRefresh);
		setCacheDeletePopulatorOptions(!doNotDelete);
	}

	/*
	<kaleidoc>
<filename>Group</filename>
<page>
<api>
	<class>Group</class>
	<method>setCacheRefreshPopulatorNbOptions</method>
	<cpp>void setCacheRefreshPopulatorNbOptions(boolean b)</cpp>
	<java>final public void setCacheRefreshPopulatorNbOptions(boolean b)</java>
	<descr>
	<p>After calling setCacheRefreshPopulatorNbOptions(true) -  GroupPopulator.postRestore() is a good place for that, KRuntime outdates the value that comes from GroupPopulator.getNbOption()  in its cache at the begining of the activate phase.
	This means that this value will be cached for the whole Activate/Render Phase but will be outdated for the next activate phase.
	They will then be requested again to the populator when needed.
	This allows to handle a group in which the nb of options changes.</p>
	</descr>
	</api>
</page>
</kaleidoc>
	*/
	void setCacheRefreshPopulatorNbOptions(boolean b){
		fCacheRefreshPopulatorNbOptions=b;
	}

	/*
	<kaleidoc>
<filename>Group</filename>
<page>
<api>
	<class>Group</class>
	<method>isCacheRefreshPopulatorNbOptions</method>
	<cpp>boolean isCacheRefreshPopulatorNbOptions()</cpp>
	<java>final public boolean isCacheRefreshPopulatorNbOptions()</java>
	<descr>
	<p>This method is the accessor for the value set using Group.setCacheRefreshPopulatorNbOptions().</p>
	</descr>
	</api>
</page>
</kaleidoc>
	*/
	boolean isCacheRefreshPopulatorNbOptions() {
		return fCacheRefreshPopulatorNbOptions;
	}


#ifdef USE_DEPRECATED
	boolean isCacheOptionImages() {
		return false;
	}

	void setCacheOptionImages(boolean cacheOptionImages) {
	}
#endif

	/*
	<kaleidoc>
<filename>Group</filename>
<page>
<api>
	<class>Group</class>
	<method>getPopulatorClass</method>
	<java>String getPopulatorClass()</java>
	<cpp>char* getPopulatorClass()</cpp>
	<descr>
	<p>Returns the "class" of the populator. This class is used to create it when needed. This class is also used to know if a populator has been set for this group (class is not null).</p>
	<p>In the C version, the ownership of the returned string is not transferred to the caller.</p>
	</descr>
	</api>
</page>
</kaleidoc>
	*/
	char* getPopulatorClass() {
		return fPopulatorClass;
	}

	char* getGroupParam() {
		return fGroupParam;
	}

	void setGroupParam(char* p) {
		ASSERT_MEMORY_OWNERSHIP(this, p);
		SAFE_FREE(fGroupParam);
		fGroupParam = p;
	}

	/*
	<kaleidoc>
<filename>Group</filename>
<page>
<api>
	<class>Group</class>
	<method>setPopulatorClass</method>
	<java>final public void setPopulatorClass(String populatorClass, String param)</java>
	<cpp>void setPopulatorClass(char* populatorClass, char* param)</cpp>
	<descr>
	<p>Modifies the populator class for this group. It also nils the populator field making the new populator being lazy instanciated from the new class the next time it will be requested.</p>
	<p>In the C version, each pointer's ownership is transferred to the Group.</p>
	</descr>
	</api>
</page>
</kaleidoc>
	*/
	void setPopulatorClass(char* populatorClass, char* populatorParam) ;

	boolean isPopulatorAvailable() {// deprecated
		return (fPopulatorClass != NULL);
	}

#ifdef USE_DEPRECATED
	GroupPopulator* getPopulator(boolean buildit) {
		return getPopulator();
	}
#endif

	/*
	<kaleidoc>
<filename>Group</filename>
<page>
<api>
	<class>Group</class>
	<method>getPopulator</method>
	<java>GroupPopulator getPopulator()</java>
	<cpp>GroupPopulator* getPopulator()</cpp>
	<descr>
	<p>Returns the instantiated populator object, instanciating it if needed from the class returned by getPopulatorClass().
	Returns null if no populator is available.</p>
	<p>In the C version, the ownership of the returned object is not transferred to the caller.</p>
	</descr>
	</api>
</page>
</kaleidoc>
	*/
	GroupPopulator* getPopulator();		
	void setPopulator(GroupPopulator* populator) ;

	/*
	<kaleidoc>
<filename>Group</filename>
<page>
<api>
	<class>Group</class>
	<method>getJitMapperClass</method>
	<java>String getJitMapperClass()</java>
	<cpp>char* getJitMapperClass()</cpp>
	<descr>
	<p>Returns the class name of the jitmapper.</p>
	<p>In the C version, the ownership of the returned string is not transferred to the caller.</p>
	</descr>
	</api>
</page>
</kaleidoc>
	*/
	char* getJitMapperClass() {
		return fJitMapperClass;
	}

	/*
	<kaleidoc>
<filename>Group</filename>
<page>
<api>
	<class>Group</class>
	<method>setJitMapperClass</method>
	<java>final public void setJitMapperClass(String jitMapperClass, String param)</java>
	<cpp>void setJitMapperClass(char* jitMapperClass, char* param)</cpp>
	<descr>
	<p>Modifies the JitMapper class for this group. This class is used in each option to instantiate a jitmapper used to render the option.</p>
	<note>This call does NOT null the already instantiated jitmappers in the options. To have these options use a JitMapper instanciated from the new class, a loop must be done on all group options (Group.getOptions())
	and a Option.setJitMapper(NULL) should be called on each. So, a new JitMapper will be lazy instanciated when needed using the new class.</note>
	<p>In the C version, each pointer's ownership is transferred to the Group.</p>
	</descr>
	</api>
</page>
</kaleidoc>
	*/
	void setJitMapperClass(char* jitMapperClass, char* param);

	/*
	<kaleidoc>
<filename>Group</filename>
<page>
<api>
	<class>Group</class>
	<method>getOptionAccepted</method>
	<java>Option getOptionAccepted()</java>
	<cpp>Option* getOptionAccepted()</cpp>
	<descr>