SplashAbout/Advanced Use: what changed

Revision 0 to 1. Removed lines have a minus sign; added lines have a plus sign.

Title: SplashAbout/Advanced Use

New		Line
1	+	- For installation, download, version and other information, see the [[SplashAbout]] page
2	+
3	+	## SplashAbout properties tester Application
4	+
5	+	- The distribution archive contains an example application with all the resources needed to experiment with advanced properties - pre-configured with Resource and External graphics, also sample license.txt and Credits
6	+	- Click the \[Help\] button to view the readme
7	+
8	+	<figure>
9	+	<img src="splashabout_properties_tester144.png" title="splashabout_properties_tester144.png" />
10	+	<figcaption>splashabout_properties_tester144.png</figcaption>
11	+	</figure>
12	+
13	+	------------------------------------------------------------------------
14	+
15	+	## Properties
16	+
17	+	When dropped onto a new application mainform, the property defaults will show a Splash Screen and About window that look something like this:
18	+
19	+	<figure>
20	+	<img src="splashabout_default_splash.png" title="splashabout_default_splash.png" />
21	+	<figcaption>splashabout_default_splash.png</figcaption>
22	+	</figure>
23	+
24	+	<figure>
25	+	<img src="splashabout_default_about.png" title="splashabout_default_about.png" />
26	+	<figcaption>splashabout_default_about.png</figcaption>
27	+	</figure>
28	+
29	+	- A normal (borderless rectangle) Splash screen displayed for 2 seconds (ShowSplash method)
30	+	- It will use the Application default icon (default=Lazarus icon)
31	+	- Title will be the Application name (default='project1')
32	+	- Colour will be clSkyBlue
33	+	- No background image
34	+	- No description
35	+	- Window size = 320px x 240px
36	+	- LCL and FPC build text
37	+	- Compilation Date/Time text
38	+	- The About screen will show (ShowAbout method)
39	+	- No License or Credits buttons
40	+	- The same text as the default Splash Screen
41	+
42	+	The default screens are probably OK for a quick one-off app that is not for commercial use. It shows useful information for a developer.
43	+
44	+	However; if you think they look a bit uninspiring, the SplashAbout component is capable of considerable customisation from its default settings, and there are many properties available to help you achieve a unique and very inspiring result.
45	+
46	+	Here are the SplashAbout properties you can change for each kind of customisation:
47	+
48	+	### Personalising the Splash screen
49	+
50	+	- Properties that affect the Splash Screen:
51	+	- The Application Title,Icon and VersionInfo (set in Project/Options)
52	+	- BackGroundColor
53	+	- BitMapBackground
54	+	- BitmapMaskColor
55	+	- BitmapMaskMono
56	+	- DelaySeconds
57	+	- Description
58	+	- Font
59	+	- FormSplashHeight
60	+	- FormSplashTextAlign
61	+	- FormSplashWidth
62	+	- Graphics
63	+	- Icon
64	+	- MaskType
65	+	- Organisation
66	+	- ShowDecription
67	+	- ShowPoweredBy
68	+	- TitleStyle
69	+	- UserTitle
70	+
71	+	### Personalising the About screen
72	+
73	+	- Properties that affect the About Screen:
74	+	- The Application Title,Icon and VersionInfo (set in Project/Options)
75	+	- Author
76	+	- BackGroundColor
77	+	- CreditLines
78	+	- CreditsTextFileName
79	+	- Description
80	+	- Font
81	+	- FormAboutHeight
82	+	- FormAboutTextAlign
83	+	- FormAboutWidth
84	+	- Graphics
85	+	- Icon
86	+	- LicenseFile
87	+	- Orgnisation
88	+	- ShowCreditButton
89	+	- ShowDecription
90	+	- LicenseFile
91	+	- SupportContact
92	+	- TitleStyle
93	+	- UserTitle
94	+
95	+	### Personalising the License Screen
96	+
97	+	- Properties that affect the License Screen:
98	+	- Author
99	+	- LicenseFile
100	+	- Organisation
101	+	- SupportContact
102	+
103	+	### Personalising the Credits Screen
104	+
105	+	- Properties that affect the Credits Screen:
106	+	- CreditLines
107	+	- CreditsTextFileName
108	+	- ShowCreditButton
109	+
110	+	------------------------------------------------------------------------
111	+
112	+	## How To...
113	+
114	+	### How to show a shaped Splash screen
115	+
116	+	Properties to set:
117	+
118	+	- BitmapMaskColor (Graphics=saResources)
119	+	- BitmapMaskMono (Graphics=saResources)
120	+	- MaskType
121	+	- Graphics
122	+
123	+	#### MaskType
124	+
125	+	- Default=saNoMask
126	+
127	+	The simple thing to do is to choose one of the built-in masks (saRoundedRect, saBigCog, saBigFlower and saBigSplash) If you choose saUserMask then you need to make a 2-colour mask graphic in the .BMP format. You can optionally also make a corresponding BitMapMaskColor image. Note: There are some example images deployed in the /exampleapp folder of the distribution archive
128	+
129	+	##### How to make a BitMapMaskMono image
130	+
131	+	- Start with a black (RGB:0,0,0)background
132	+	- Make your contigious shape using a white (RGB:255,255,255) shape
133	+	- Reduce the image to a 2-color palette
134	+	- Save the file as a Windows Bitmap (.BMP) and use it to set the BitmapMaskColor property
135	+	- It should NOT be run-length encoded (RLE)
136	+
137	+	If you want a shaped colour splash screen then you need to make a corresponding BitMapColor image
138	+
139	+	##### How to make a BitmapMaskColor image
140	+
141	+	You would normally do this before making the BitmapMaskMono image
142	+
143	+	- Make with an colour image that has a white (RGB:255,255,255) background
144	+	- You can use a selection tool to isolate the background then paint it white in a graphics application
145	+	- Save the file as a .JPG and use it to set the BitmapMaskColor property
146	+	- To make a corresponding BitmapMaskColor image:
147	+	- Invert the selection, and paint it black (RGB:0.0.0)
148	+	- Reduce the image to a 2-color palette
149	+	- Save the new image as a non-RLE Windows Bitmap file (.BMP) and use it to set the BitmapMaskMono property
150	+
151	+	------------------------------------------------------------------------
152	+
153	+	### How to show a license button on the About screen
154	+
155	+	Properties to set:
156	+
157	+	- LicenseFile
158	+	- Optional:
159	+	- Author
160	+	- Organisation
161	+	- SupportContact
162	+
163	+	#### LicenseFile
164	+
165	+	- Default=saNone
166	+
167	+	##### Standard licences (GPL etc)
168	+
169	+	- If you set LicenseFile to one of the standard license type (saGPL,saLGPL,saMIT or saModifiedGPL) then the License button will appear on the About dialog
170	+	- When clicked, the License button shows a modal window with the appropriate license text
171	+	- The text is stored as a resource, so no need for external files
172	+	- The text of the standard license can be modified by setting the Author Organisation and SupportContact properties
173	+
174	+	##### User licenses
175	+
176	+	- If you set LicenseFile to saUserFile then the License button will appear on the About dialog
177	+	- When clicked, the License button shows a modal window with text
178	+	- The text will come from a file you create yourself which must be called 'license.txt' and deployed in the same folder as your executable (see exampleapp)
179	+	- You can use the following tokens in 'license.txt'
180	+	- All instances of \<name of author\> are replaced with the Author property
181	+	- All instances of \<contact\> are replaced with the SupportContact property
182	+	- All instances of \<copyright holders\> are replaced with the Organisation property
183	+	- All instances of \<year\> are replaced with the compilation date
184	+
185	+	------------------------------------------------------------------------
186	+
187	+	### How to show a Credits button on the About screen
188	+
189	+	Properties to set:
190	+
191	+	- ShowCreditButton
192	+	- CreditLines
193	+	- Optional
194	+	- Font (inherited)
195	+	- BackgroundColor (inherited)
196	+	- CreditTextFileName
197	+
198	+	#### ShowCreditButton
199	+
200	+	- Default-False
201	+	- If set to True, then the Credits button will appear on the About dialog
202	+	- When clicked it will show either:
203	+	- The contents of CreditLines
204	+	- or the contents of a text file (default name='credits.txt') deployed in the same folder as your executable
205	+	- If both contain no text, then default text is shown
206	+	- If both contain text, then 'credits'txt' will be shown in preference
207	+	- The text will scroll upwards, and repeat until the user clicks the close button
208	+	- The text will be centre-justified
209	+
210	+	#### CreditLines
211	+
212	+	- default=(empty)
213	+	- Use the Object inspector to write your credits text.
214	+
215	+	#### CreditTextFileName
216	+
217	+	- This can be set so that is doesn't clash with any existing deployed text file
218	+
219	+	------------------------------------------------------------------------
220	+
221	+	### How to show a 'Powered by Lazarus' pre-splash graphic
222	+
223	+	Properties to set:
224	+
225	+	- ShowPoweredBy
226	+
227	+	That's it!
228	+
229	+	------------------------------------------------------------------------
230	+
231	+	### How to show different text in the Splash and About screens
232	+
233	+	Properties to set:
234	+
235	+	- ShowDescription
236	+	- Description
237	+	- TitleStyle
238	+	- UserTitle
239	+	- Organisation
240	+	- FormSplashTextAlign
241	+	- FormAboutTextAlign
242	+	- LicenseFile
243	+	- Application VersionInfo
244	+
245	+	##### Description and ShowDescription
246	+
247	+	- Use the Object Inspector to write a short description of your application and set ShowDescription=True
248	+	- The Description text will show on both the Splash and About dialogs
249	+	- The Description text will replace the Build and Platform information on both dialogs
250	+
251	+	##### TitleStyle and UserTitle
252	+
253	+	- If TitleStyle=saUserTitle then the UserTitle text will appear on the Splash and About dialogs
254	+	- If TitleStyle=saForm the Caption text of your mainform will be used
255	+	- If TitleStyle=saApplication, the Application title (set in Project/Options) will be used
256	+	- The text will also appear as the caption text of all dialogs
257	+
258	+	##### Organisation
259	+
260	+	- If set, then the text will appear below the UserTitle on the Splash and About dialogs
261	+
262	+	##### FormSplashTextAlign and FormAboutTextAlign
263	+
264	+	- You might want to set these if you have a background image that has a blank area for text on one side
265	+
266	+	##### LicenseFile
267	+
268	+	- If this is anything other than LicenseFile=saNone, then the text 'Released under \<licensetype\> license' will appear at the bottom of the Splash and About dialogs where \<licensetype\> is
269	+	- LicenseFile=saGPL: 'GPL'
270	+	- LicenseFile=saLGPL: 'LGPL'
271	+	- LicenseFile=saMIT: 'MIT'
272	+	- LicenseFile=saModifiedGPL: 'Modified GPL'
273	+	- LicenseFile=saUserFile: 'proprietry'
274	+
275	+	##### Application Version info
276	+
277	+	- If you enable Version Information in the Project/Options then it will appear in both Splash and About dialogs
278	+
279	+	------------------------------------------------------------------------
280	+
281	+	### How to show a graphic in the Splash and About screens
282	+
283	+	Properties to set:
284	+
285	+	- BitmapBackground
286	+	- Optional:
287	+	- FormSplashWidth
288	+	- FormSplashHeight
289	+	- FormAboutWidth
290	+	- FormAboutHeight
291	+
292	+	##### BitmapBackground
293	+
294	+	- Use the Object Inspector to load a graphic file (most types supported)
295	+	- The graphic will override the BackgroundColor setting
296	+	- The graphic will stretch to fit the Splash and About dialogs
297	+
298	+	##### FormSplashWidth/Height and FormAboutWidth/Height
299	+
300	+	- You can set these to any reasonable values and the controls and background will stretch/move as necessary
301	+
302	+	------------------------------------------------------------------------
303	+
304	+	### How to set a custom Icon
305	+
306	+	Properties to set:
307	+
308	+	- Icon
309	+	- TitleStyle
310	+
311	+	##### TitleStyle
312	+
313	+	- To show a custom Icon then TitleStyle must be set to saUserTitle
314	+
315	+	##### Icon
316	+
317	+	- Use the Object Inspector to set an appropriate icon
318	+	- It will be shown on all dialogs
319	+	- If TitleStyle is set to saForm then the mainform's icon will always be shown
320	+	- If TitleStyle is set to saApplication then the application's always icon will be shown
321	+	- If no custom icons have been set for either, the the default Lazarus icon is displayed
322	+
323	+	------------------------------------------------------------------------
324	+
325	+	### How (or why) to avoid a bigger executable by using external graphic files
326	+
327	+	SplashAbout has been designed from the start to be very lightweight. Splash and About dialogs are hardly the most important part of an application so the component is designed to add as little as possible in both filesize and effort. Lazarus/fpc are extremely efficient in storing resources in executables, however adding SplashAbout with embedded graphics will make your executable bigger. If you choose to set a huge Splash and/or About dialog with correspondingly huge graphics, maybe it will be worth 'going external'
328	+
329	+	Here are the stats:
330	+
331	+	- Typical Win64 application using SplashAbout with every graphics property set and stored in the executable = 5MB
332	+	- Typical Win64 application using SplashAbout with all graphics deployed externally=3.7MB
333	+
334	+	If this difference is important to your particular deployment, then read on...
335	+
336	+	Properties to set:
337	+
338	+	- Graphics
339	+	- ExternalFileBackgroundImage
340	+	- ExternalFileIcon
341	+	- ExternalFileMaskMonoImage
342	+	- ExternalFileMaskColorImage
343	+	- ExternalFileOptions
344	+
345	+	##### Graphics
346	+
347	+	- Default=saUseResources
348	+	- If Graphics=saExternalFiles then the ExternalFile\<propertyname\> properties will be used
349	+
350	+	##### ExternalFile\<propertyname\>
351	+
352	+	- All ExternalFile properties accept a simple filename as text
353	+	- All external files MUST be in the executable's deployed folder
354	+	- SplashAbout will test at runtime to see if the appropriate file is present, and will display an error message if it is absent or in the wrong folder
355	+
356	+	##### ExternalFileOptions
357	+
358	+	- Setting these will allow you to use some External files and some resources together
359	+
360	+	------------------------------------------------------------------------
361	+
362	+	### How to use a large background image
363	+
364	+	- By default, ShowSplash respects the dimensions you set in the Splash and About Formwidth and Formheight properties. It will stretch/compress any BackgroundImage to fit the window which is preferred behaviour. You may, however want to resize the Splash and About windows to fit your background graphic, or even avoid all resizing altogether.
365	+	- Note: ResizeMode has no effect on shaped Splash screens - they are always resized to fit the mask.
366	+
367	+	Properties to set:
368	+
369	+	- ResizeMode
370	+	- BackgroundImage
371	+
372	+	##### ResizeMode
373	+
374	+	- Default=saResizeGraphic
375	+	- If ResizeMode=saResizeWindow, then SplashAbout will resize the Splash and About windows to the loaded graphic dimensions.
376	+	- If ResizeMode=saNoResize, then the Splash and About width/height properties will be respected, and the BackgroundImage will display without stretching or compressing.
377	+
378	+	------------------------------------------------------------------------
379	+
380	+	### How to deploy an application that uses the SplashAbout component
381	+
382	+	- If Graphics=saResources then no external files are necessary
383	+	- If ShowCreditButton=True, CreditLines is empty then you will need to deploy a 'credits.txt' textfile (CreditsTextfileName can set the filename) in the same folder as your deployed executable.
384	+	- This could be a good option if you want to update the Credits screen without recompiling and re-deploying the executable
385	+
386	+	------------------------------------------------------------------------
387	+
388	+	## Is it OK to...
389	+
390	+	Some information about licensing, updating the source etc.
391	+
392	+	### Is it OK to use SplashAbout in a commercial application?
393	+
394	+	- Splashabout is released under the LGPL licence, so the short answer is 'yes' I would hope for a mention in the Credits screen :)
395	+	- Here is the relevant text of the LGPL license:
396	+
397	+	` This library is free software; you can redistribute it and/or modify it`\
398	+	` under the terms of the GNU Library General Public License as published by`\
399	+	` the Free Software Foundation; either version 2 of the License, or (at your`\
400	+	` option) any later version.`\
401	+	` This program is distributed in the hope that it will be useful, but WITHOUT`\
402	+	` ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or`\
403	+	` FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public License`\
404	+	` for more details.`
405	+
406	+	### Is it OK to alter/change the code for my own version of SplashAbout?
407	+
408	+	- Of course! That's what open source software is all about
409	+	- \[[mailto:minesadorada@charcodelvalle.com](mailto:minesadorada@charcodelvalle.com)\\| Email me\] with your updates as a courtesy and perhaps I could incorporate them here
410	+	- In the spirit of open source, please retain acknowledgement of my source code
411	+
412	+	Page written by Torrenter 20:06, 2 June 2014 (CEST)
413	+
414	+	------------------------------------------------------------------------
415	+
416	+	## See Also
417	+
418	+	[[SplashAbout\|SplashAbout component main page]]
419	+
420	+	---
421	+	From the Free Pascal wiki, page "SplashAbout/Advanced Use", as it stood on 2014-06-04 after a change by Torrenter, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).
422	+	Category: Components

Back to history