/plugin API/Plugin.cs
C# | 559 lines | 278 code | 83 blank | 198 comment | 34 complexity | 8a4303111950c7e1d375f6dd1ef6c098 MD5 | raw file
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}