/plugin API/Plugin.cs

  1/**
  2 * Plugin.cs
  3 * 
  4 * All the functionality for a plugin.
  5 * 
  6 * * * * * * * * *
  7 * 
  8 * Copyright 2012 Simplare
  9 * 
 10 * This code is part of the Stoffi Music Player Project.
 11 * Visit our website at: stoffiplayer.com
 12 *
 13 * This program is free software; you can redistribute it and/or
 14 * modify it under the terms of the GNU General Public License
 15 * as published by the Free Software Foundation; either version
 16 * 3 of the License, or (at your option) any later version.
 17 * 
 18 * See stoffiplayer.com/license for more information.
 19 **/
 20
 21using System;
 22using System.Collections.Generic;
 23using System.Collections.Specialized;
 24using System.Collections.ObjectModel;
 25using System.ComponentModel;
 26using System.Drawing;
 27using System.Globalization;
 28using System.Linq;
 29using System.Text;
 30using System.Xml.Serialization;
 31
 32namespace Stoffi.Plugins
 33{
 34	/// <summary>
 35	/// The plugin interface which will make available stoffi functionality for the plugin programmer.
 36	/// </summary>
 37	public class Plugin
 38	{
 39		#region Members
 40		protected PluginType pluginType = PluginType.Unknown;
 41		#endregion
 42
 43		#region Properties
 44
 45		/// <summary>
 46		/// Gets the type of the plugin.
 47		/// </summary>
 48		public PluginType Type { get { return pluginType; } }
 49
 50		/// <summary>
 51		/// Gets the name of the author of the plugin.
 52		/// </summary>
 53		public virtual string Author { get; protected set; }
 54
 55		/// <summary>
 56		/// Gets the website of the plugin.
 57		/// </summary>
 58		public virtual string Website { get; protected set; }
 59
 60		/// <summary>
 61		/// Gets or sets the version of the plugin.
 62		/// </summary>
 63		public virtual Version Version { get; protected set; }
 64
 65		/// <summary>
 66		/// Gets the version of the plugin platform that the
 67		/// plugin was built for.
 68		/// </summary>
 69		public Version PlatformVersion { get; private set; }
 70
 71		/// <summary>
 72		/// Gets the identifier of the plugin.
 73		/// </summary>
 74		public string ID { get; private set; }
 75
 76		/// <summary>
 77		/// Gets or sets the list of supported languages.
 78		/// </summary>
 79		public List<Language> Languages { get; set; }
 80
 81		/// <summary>
 82		/// Gets or sets the IETF tag of the currently active culture.
 83		/// </summary>
 84		public string CurrentCulture { get; set; }
 85
 86		/// <summary>
 87		/// Gets the currently active language.
 88		/// </summary>
 89		public Language CurrentLanguage
 90		{
 91			get
 92			{
 93				foreach (Language l in Languages)
 94					if (l.Culture == CurrentCulture)
 95						return l;
 96				foreach (Language l in Languages)
 97					if (l.Culture == "en-US")
 98						return l;
 99				return null;
100			}
101		}
102
103		/// <summary>
104		/// The default language (English if found, otherwise first in list).
105		/// </summary>
106		public Language DefaultLanguage
107		{
108			get
109			{
110				foreach (Language l in Languages)
111					if (l.Culture == "en-US")
112						return l;
113				if (Languages.Count > 0)
114					return Languages[0];
115				return null;
116			}
117		}
118
119		/// <summary>
120		/// Gets the list of settings used to configure the plugin.
121		/// </summary>
122		public ObservableCollection<Setting> Settings { get; private set; }
123
124		/// <summary>
125		/// Gets the list of status labels of the plugin.
126		/// </summary>
127		public List<StatusLabel> StatusLabels { get; private set; }
128
129		#endregion
130
131		#region Constructor
132
133		/// <summary>
134		/// Creates an instance of a plugin.
135		/// </summary>
136		/// <param name="id">A string identifying the plugin</param>
137		/// <param name="version">The assembly version</param>
138		/// <param name="platformVersion">The minimum version required of the plugin platform</param>
139		public Plugin(string id, Version version, Version platformVersion)
140		{
141			this.ID = id;
142			this.Version = version;
143			this.PlatformVersion = platformVersion;
144			PlatformVersion = new Version(0, 4);
145			Languages = new List<Language>();
146			Settings = new ObservableCollection<Setting>();
147			StatusLabels = new List<StatusLabel>();
148		}
149
150		#endregion
151
152		#region Methods
153
154		#region Public
155
156		/// <summary>
157		/// Translates a string.
158		/// 
159		/// It first tries to find the string in the current language,
160		/// if not found it will search in the default language,
161		/// if still not found it will return the ID of the string.
162		/// </summary>
163		/// <param name="id">The ID of the translation string</param>
164		/// <returns>The string localized according to the current culture</returns>
165		public string T(string id)
166		{
167			Language l = CurrentLanguage;
168			if (l != null)
169				foreach (Translation t in l.Translations)
170					if (t.ID == id)
171						return t.Text.Replace("\\n", "\n");
172
173			l = DefaultLanguage;
174			if (l != null)
175				foreach (Translation t in l.Translations)
176					if (t.ID == id)
177						return t.Text.Replace("\\n", "\n");
178
179			return id;
180		}
181 
182		/// <summary>
183		/// Called when the plugin is installed.
184		/// </summary>
185		///  <returns>True if set up was successful, otherwise false</returns>
186		public virtual bool OnInstall()
187		{
188			return true;
189		}
190		
191		/// <summary>
192		/// Called when the plugin is activated
193		/// </summary>
194		///  <returns>True if set up was successful, otherwise false</returns>
195		public virtual bool OnStart()
196		{
197			return true;
198		}
199
200		
201		/// <summary>
202		/// Called when the plugin is deactivated
203		/// </summary>
204		///  <returns>True if tear down was successful, otherwise false</returns>
205		public virtual bool OnStop()
206		{
207			return true;
208		}
209		
210		/// <summary>
211		/// Called when the plugin is uninstalled.
212		/// </summary>
213		///  <returns>True if tear down was successful, otherwise false</returns>
214		public virtual bool OnUninstall()
215		{
216			return true;
217		}
218		
219		/// <summary>
220		/// Updates the plugin.
221		/// </summary>
222		public virtual void Refresh()
223		{
224		}
225
226		/// <summary>
227		/// Updates the plugin.
228		/// </summary>
229		/// /// <param name="deltaTime">Time elapsed since last tick</param>
230		public virtual void Refresh(float deltaTime)
231		{
232		}
233
234		#endregion
235
236		#region Protected
237
238		#endregion
239
240		#endregion
241	}
242
243	#region Enums
244
245	/// <summary>
246	/// A type of a plugin.
247	/// </summary>
248	public enum PluginType
249	{
250		/// <summary>
251		/// A plugin providing a source of music.
252		/// </summary>
253		Source,
254
255		/// <summary>
256		/// A plugin manipulating the sound.
257		/// </summary>
258		Filter,
259
260		/// <summary>
261		/// A plugin providing a visualization of the sound.
262		/// </summary>
263		Visualizer,
264
265		/// <summary>
266		/// A plugin of unknown type.
267		/// </summary>
268		Unknown
269	}
270
271	#endregion
272
273	#region Data structures
274
275	/// <summary>
276	/// Describes a language containing a collection of localized strings.
277	/// </summary>
278	public class Language
279	{
280		/// <summary>
281		/// Gets or sets the IETF culture tag of the language.
282		/// </summary>
283		public string Culture { get; set; }
284
285		/// <summary>
286		/// Gets or sets the collection of localized strings.
287		/// </summary>
288		public List<Translation> Translations { get; set; }
289	}
290
291	/// <summary>
292	/// Describes a single localized string.
293	/// </summary>
294	public class Translation
295	{
296		/// <summary>
297		/// Gets or sets the ID of the translation string.
298		/// </summary>
299		[XmlAttribute("ID")]
300		public string ID { get; set; }
301
302		/// <summary>
303		/// Gets or sets the localized string.
304		/// </summary>
305		[XmlAttribute("Text")]
306		public string Text { get; set; }
307	}
308
309	/// <summary>
310	/// Describes a status of the plugin.
311	/// </summary>
312	public class StatusLabel : INotifyPropertyChanged
313	{
314		#region Members
315
316		private String label;
317		private String status;
318
319		#endregion
320
321		#region Properties
322
323		/// <summary>
324		/// Gets or sets the string of the label.
325		/// </summary>
326		public String Label
327		{
328			get { return label; }
329			set { label = value; OnPropertyChanged("Label"); }
330		}
331
332		/// <summary>
333		/// Gets or sets the string describing the current status.
334		/// </summary>
335		public String Status
336		{
337			get { return status; }
338			set { status = value; OnPropertyChanged("Status"); }
339		}
340
341		#endregion
342
343		#region Methods
344
345		/// <summary>
346		/// Dispatches the PropertyChanged event
347		/// </summary>
348		/// <param name="name">The name of the property that was changed</param>
349		public void OnPropertyChanged(string name)
350		{
351			if (PropertyChanged != null)
352				PropertyChanged(this, new PropertyChangedEventArgs(name));
353		}
354
355		#endregion
356
357		#region Events
358
359		/// <summary>
360		/// Occurs when the property of the item is changed
361		/// </summary>
362		public event PropertyChangedEventHandler PropertyChanged;
363
364		#endregion
365	}
366
367	/// <summary>
368	/// A plugin setting.
369	/// </summary>
370	public class Setting : INotifyPropertyChanged
371	{
372		#region Members
373
374		private String id;
375		private Object value;
376		private Object maximum;
377		private Object minimum;
378		private List<Object> possibleValues = new List<object>();
379		private Type type;
380		private Boolean isVisible;
381
382		#endregion
383
384		#region Properties
385
386		/// <summary>
387		/// Gets or sets the ID of the setting.
388		/// </summary>
389		public String ID
390		{
391			get { return id; }
392			set { id = value; OnPropertyChanged("ID"); }
393		}
394
395		/// <summary>
396		/// Gets or sets the type of the setting's value.
397		/// </summary>
398		[XmlIgnore()]
399		public Type Type
400		{
401			get { return type; }
402			set { type = value; OnPropertyChanged("Type"); }
403		}
404
405		/// <summary>
406		/// Gets or sets the value of the setting.
407		/// </summary>
408		[XmlIgnore()]
409		public Object Value
410		{
411			get { return value; }
412			set { this.value = value; OnPropertyChanged("Value"); }
413		}
414
415		/// <summary>
416		/// Gets or sets the maximum value possible.
417		/// </summary>
418		/// <remarks>
419		/// Used with numerical types to create a slider.
420		/// </remarks>
421		public Object Maximum
422		{
423			get { return maximum; }
424			set { maximum = value; OnPropertyChanged("Maximum"); }
425		}
426
427		/// <summary>
428		/// Gets or sets the minimum value possible.
429		/// </summary>
430		/// <remarks>
431		/// Used with numerical types to create a slider along with the Maximum property.
432		/// </remarks>
433		public Object Minimum
434		{
435			get { return minimum; }
436			set { minimum = value; OnPropertyChanged("Minimum"); }
437		}
438
439		/// <summary>
440		/// Gets or sets the list of possible values for the setting.
441		/// </summary>
442		/// <remarks>
443		/// Used to create a dropdown menu.
444		/// </remarks>
445		public List<Object> PossibleValues
446		{
447			get { return possibleValues; }
448			set { possibleValues = value; OnPropertyChanged("PossibleValues"); }
449		}
450
451		/// <summary>
452		/// Gets or sets whether or not the setting should be visible to the user.
453		/// </summary>
454		public Boolean IsVisible
455		{
456			get { return isVisible; }
457			set { isVisible = value; OnPropertyChanged("IsVisible"); }
458		}
459
460		/// <summary>
461		/// Gets or sets a serialized representation of the Type property.
462		/// </summary>
463		/// <remarks>
464		/// Enables the class to be serialized for saving in XML file.
465		/// </remarks>
466		[XmlElement(ElementName = "Type")]
467		public String SerializedType
468		{
469			get
470			{
471				return type == null ? null : type.AssemblyQualifiedName;
472			}
473			set
474			{
475				type = Type.GetType(value);
476			}
477		}
478
479		/// <summary>
480		/// Gets or sets a serialized representation of the Value property.
481		/// </summary>
482		/// <remarks>
483		/// Enables the class to be serialized for saving in XML file.
484		/// </remarks>
485		[XmlElement(ElementName = "Value")]
486		public String SerializedValue
487		{
488			get
489			{
490				if (SerializedType == typeof(Color).AssemblyQualifiedName)
491				{
492					try
493					{
494						Color c = (Color)value;
495						return c.IsNamedColor ? c.Name : "#" + c.Name.ToUpper();
496					}
497					catch
498					{
499						return null;
500					}
501				}
502				else
503					return value == null ? null : value.ToString();
504			}
505			set
506			{
507				string t = SerializedType;
508				if (t == typeof(Color).AssemblyQualifiedName)
509				{
510					try
511					{
512						this.value = ColorTranslator.FromHtml(value);
513					}
514					catch
515					{
516						this.value = value;
517					}
518				}
519				else if (t == typeof(Boolean).AssemblyQualifiedName)
520					this.value = Boolean.Parse(value);
521
522				else if (t == typeof(Int32).AssemblyQualifiedName)
523					this.value = Int32.Parse(value);
524
525				else if (t == typeof(Double).AssemblyQualifiedName)
526					this.value = Double.Parse(value);
527
528				else
529					this.value = value;
530			}
531		}
532
533		#endregion
534
535		#region Methods
536
537		/// <summary>
538		/// Dispatches the PropertyChanged event
539		/// </summary>
540		/// <param name="name">The name of the property that was changed</param>
541		public void OnPropertyChanged(string name)
542		{
543			if (PropertyChanged != null) PropertyChanged(this, new PropertyChangedEventArgs(name));
544		}
545
546		#endregion
547
548		#region Events
549
550		/// <summary>
551		/// Occurs when the property of the item is changed
552		/// </summary>
553		public event PropertyChangedEventHandler PropertyChanged;
554
555		#endregion
556	}
557
558	#endregion
559}