~ubuntu-branches/ubuntu/trusty/monodevelop/trusty-proposed

An extension node is an element registered by an add-in in an extension point. A host can get nodes registered in an extension point using methods such as <see cref="M:Mono.Addins.AddinManager.GetExtensionNodes(System.String)" />, which returns a collection of ExtensionNode objects.

</para>

<para>

ExtensionNode will normally be used as a base class of more complex extension point types. The most common subclass is <see cref="T:Mono.Addins.TypeExtensionNode" />, which allows registering a class implemented in an add-in.

</para>

<para>

EXAMPLE: An application has a toolbar that must be extensible by add-ins. The application could define the following extension node type:

</para>

public class ToolbarItemNode: ExtensionNode

{

[NodeAttribute]

string icon;

[NodeAttribute]

string label;

public string Icon {

get { return icon; }

}

public string Label {

get { return label; }

}

</code>

</example>

<para>

In the implementation of an ExtensionNode, the <see cref="T:Mono.Addins.NodeAttributeAttribute" /> attribute can be applied to fields to specify which attributes must be loaded from the node.

</para>

<para>

The extension point could be defined like this:

</para>

...

</ExtensionPoint>

...

</Addin>

</code>

</example>

<para>

An add-in could extend the toolbar by registering new nodes in the extension point like this:

</para>

...

</Extension>

...

</Addin>

</code>

</example>

<para>

To create the toolbar, the host application would get the nodes registered in the extension point:

</para>

foreach (ToolbarItemNode node in AddinManager.GetExtensionNodes ("/MainWindow/Toolbar")) {

Gtk.ToolButton it = new Gtk.ToolButton (new Gtk.Image (node.Icon, IconSize.SmallToolbar), node.Label);

// Add the button to the toolbar

}

</code>

</example>

</remarks>

</Docs>

<MemberType>Constructor</MemberType>

<Docs>

<summary>Creates an extension node.</summary>

</Docs>

100

101

</AssemblyInfo>

102

</Member>

103

104

105

<MemberType>Property</MemberType>

106

107

<ReturnType>Mono.Addins.RuntimeAddin</ReturnType>

108

</ReturnValue>

109

<Docs>

110

<summary>The add-in that registered this extension node.</summary>

111

<value>The add-in that created the node.</value>

112

<remarks>This property provides access to the resources and types of the add-in that created this extension node.</remarks>

113

</Docs>

114

115

116

</AssemblyInfo>

117

</Member>

118

119

120

<MemberType>Property</MemberType>

121

122

<ReturnType>Mono.Addins.ExtensionNodeList</ReturnType>

123

</ReturnValue>

124

<Docs>

125

<summary>Child nodes of this extension node.</summary>

126

<value>A list of child nodes.</value>

127

128

</Docs>

129

130

131

</AssemblyInfo>

132

</Member>

133

134

135

<MemberType>Property</MemberType>

136

137

138

</AssemblyInfo>

139

140

<ReturnType>Mono.Addins.ExtensionContext</ReturnType>

141

</ReturnValue>

142

<Docs>

143

<summary>To be added.</summary>

144

<value>To be added.</value>

145

<remarks>To be added.</remarks>

146

</Docs>

147

</Member>

148

149

150

<MemberType>Event</MemberType>

151

152

<ReturnType>Mono.Addins.ExtensionNodeEventHandler</ReturnType>

153

</ReturnValue>

154

<Docs>

155

<summary>To be added.</summary>

156

<remarks>To be added.</remarks>

157

</Docs>

158

159

160

</AssemblyInfo>

161

</Member>

162

163

164

<MemberType>Method</MemberType>

165

166

<ReturnType>System.Object[]</ReturnType>

167

</ReturnValue>

168

169

<Docs>

170

<summary>Returns the child objects of a node.</summary>

171

<returns>An array of child objects.</returns>

172

<remarks>This method only works if all children of this node are of type <see cref="T:Mono.Addins.TypeExtensionNode" />. The returned array is composed by all objects created by calling the <see cref="M:Mono.Addins.TypeExtensionNode.GetInstance()" /> method for each node.</remarks>

173

</Docs>

174

175

176

</AssemblyInfo>

177

</Member>

178

179

180

<MemberType>Method</MemberType>

181

182

<ReturnType>System.Object[]</ReturnType>

183

</ReturnValue>

184

185

186

</Parameters>

187

<Docs>

188

<param name="reuseCachedInstance">True if the method can reuse instances created in previous calls.</param>

189

<summary>Returns the child objects of a node.</summary>

190

<returns>An array of child objects.</returns>

191

192

</Docs>

193

194

195

</AssemblyInfo>

196

</Member>

197

198

199

<MemberType>Method</MemberType>

200

201

<ReturnType>System.Object[]</ReturnType>

202

</ReturnValue>

203

204

205

</Parameters>

206

<Docs>

207

<param name="arrayElementType">Type of the return array elements.</param>

208

<summary>Returns the child objects of a node (with type check).</summary>

209

<returns>An array of child objects.</returns>

210

211

212

<para>

213

A <see cref="T:System.InvalidOperationException" /> exception is thrown if one of the found child objects is not a subclass of the provided type.

214

</para></remarks>

215

</Docs>

216

217

218

</AssemblyInfo>

219

</Member>

220

221

222

<MemberType>Method</MemberType>

223

224

<ReturnType>System.Object[]</ReturnType>

225

</ReturnValue>

226

227

228

229

</Parameters>

230

<Docs>

231

<param name="arrayElementType">Type of the return array elements.</param>

232

<param name="reuseCachedInstance">True if the method can reuse instances created in previous calls.</param>

233

<summary>Returns the child objects of a node (with type check).</summary>

234

<returns>An array of child objects.</returns>

235

236

<para>This method only works if all children of this node are of type <see cref="T:Mono.Addins.TypeExtensionNode" />. The returned array is composed by all objects created by calling the <see cref="M:Mono.Addins.TypeExtensionNode.CreateInstance(System.Type)" /> method for each node (or <see cref="M:Mono.Addins.TypeExtensionNode.GetInstance(System.Type)" /> if reuseCachedInstance is set to true).</para>

237

<para>

238

A <see cref="T:System.InvalidOperationException" /> exception will be thrown if one of the found child objects is not a subclass of the provided type.

239

</para>

240

</remarks>

241

</Docs>

242

243

244

</AssemblyInfo>

245

</Member>

246

247

248

<MemberType>Property</MemberType>

249

250

<ReturnType>System.Boolean</ReturnType>

251

</ReturnValue>

252

<Docs>

253

<summary>Specifies whether the extension node has as an Id or not.</summary>

254

<value>True if this node has an user-specified id.</value>

255

<remarks>It is not mandatory to specify an 'id' for a node. When none is provided, the add-in manager will automatically generate an unique id for the node. This property will return true if an 'id' was provided for the node, and false if the id was assigned by the add-in manager.</remarks>

256

</Docs>

257

258

259

</AssemblyInfo>

260

</Member>

261

262

263

<MemberType>Property</MemberType>

264

265

<ReturnType>System.String</ReturnType>

266

</ReturnValue>

267

<Docs>

268

<summary>Identifier of the node.</summary>

269

<value>Identifier of the node.</value>

270

<remarks>It is not mandatory to specify an 'id' for a node. When none is provided, the add-in manager will automatically generate an unique id for the node. The <see cref="P:Mono.Addins.ExtensionNode.HasId" /> property can be used to know if the 'id' has been specified by the developer or not.</remarks>

271

</Docs>

272

273

274

</AssemblyInfo>

275

</Member>

276

277

278

<MemberType>Method</MemberType>

279

280

<ReturnType>System.Void</ReturnType>

281

</ReturnValue>

282

283

<Docs>

284

<summary>Notifies that the owner add-in has been loaded.</summary>

285

<remarks>This overridable method is called when the add-in that registered this node has been loaded in memory.</remarks>

286

</Docs>

287

288

289

</AssemblyInfo>

290

</Member>

291

292

293

<MemberType>Method</MemberType>

294

295

<ReturnType>System.Void</ReturnType>

296

</ReturnValue>

297

298

<Docs>

299

<summary>Notifies that the owner add-in has been unloaded.</summary>

300

<remarks>This overridable method is called when the add-in that registered this node has been unloaded from memory.</remarks>

301

</Docs>

302

303

304

</AssemblyInfo>

305

</Member>

306

307

308

<MemberType>Method</MemberType>

309

310

<ReturnType>System.Void</ReturnType>

311

</ReturnValue>

312

313

314

</Parameters>

315

<Docs>

316

<param name="node">The new child node.</param>

317

<summary>Notifies the addition of a child node.</summary>

318

<remarks>This method is called when a new child is added to this node. It may be due to changes in conditions or for an add-in being enabled. </remarks>

319

</Docs>

320

321

322

</AssemblyInfo>

323

</Member>

324

325

326

<MemberType>Method</MemberType>

327

328

<ReturnType>System.Void</ReturnType>

329

</ReturnValue>

330

331

332

</Parameters>

333

<Docs>

334

<param name="node">The removed node.</param>

335

<summary>Notifies the removal of a child node.</summary>

336

<remarks>This method is called when a child of this node is removed. It may be due to changes in conditions or for an add-in being disabled. </remarks>

337

</Docs>

338

339

340

</AssemblyInfo>

341

</Member>

342

343

344

<MemberType>Method</MemberType>

345

346

<ReturnType>System.Void</ReturnType>

347

</ReturnValue>

348

349

<Docs>

350

<summary>Notifies changes in child nodes.</summary>

351

<remarks>This method is called when child nodes are added or removed. It may be due to changes in conditions, or to add-ins being enabled or disabled.</remarks>

352

</Docs>

353

354

355

</AssemblyInfo>

356

</Member>

357

358

359

<MemberType>Property</MemberType>

360

361

362

</AssemblyInfo>

363

364

<ReturnType>Mono.Addins.ExtensionNode</ReturnType>

365

</ReturnValue>

366

<Docs>

367

<summary>To be added.</summary>

368

<value>To be added.</value>

369

<remarks>To be added.</remarks>

370

</Docs>

371

</Member>

372

373

374

<MemberType>Property</MemberType>

375

376

<ReturnType>System.String</ReturnType>

377

</ReturnValue>

378

<Docs>

379

<summary>Location of this node in the extension tree.</summary>

380

381

382

<para>

383

The node path is composed by the path of the extension point where it is defined, the identifiers of its parent nodes, and its own identifier. For example:

384

</para>

385

386

387

388

389

390

391

</ItemSet>

392

</Extension>

393

</code>

394

</example>

395

<para>

396

The path of the node "NewProject" would be "/MonoDevelop/Workbench/MainMenu/File/NewProject".

397

</para>

398

</remarks>

399

</Docs>

400

401

402

</AssemblyInfo>

403

</Member>

404

405

406

<MemberType>Method</MemberType>

407

408

<ReturnType>System.Void</ReturnType>

409

</ReturnValue>

410

411

412

</Parameters>

413

<Docs>

414

<param name="elem">To be added.</param>

415

<summary>To be added.</summary>

416

417

<para>ExtensionNode subclasses can override this method to take control on the process of loading an ExtensionNode instance out of an extension node. If the Read method is overriden (and if it doesn't call the base class) [<see cref="T:Mono.Addins.NodeAttributeAttribute" />] attributes will be ignored.</para>

418

<para>The following example would be equivalent to the example shown for the class <see cref="T:Mono.Addins.NodeAttributeAttribute" />, but this implementation would be more efficient since no reflection would be involved:</para>

419

420

421

public class FileTemplateNode: ExtensionNode

422

{

423

string resource;

424

string name;

425

426

public string Name {

427

get { return name != null ? name : Id; }

428

}

429

430

public virtual string GetContent ()

431

{

432

using (StreamReader sr = new StreamReader(Addin.GetResource (resource))) {

433

return sr.ReadToEnd ();

434

}

435

}

436

437

protected override void Read (NodeElement elem)

438

{

439

resource = elem.GetAttribute ("resource-name");

440

name = elem.GetAttribute ("name");

441

}

442

}

443

</code>

444

</example>

445

</remarks>

446

</Docs>

447

448

449

</AssemblyInfo>

450

</Member>

451

</Members>

452

</Type>

Older »